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IBM Time Sharing System 
Assembler User 
Systems Macro Instructions 



Provides the information necessary to code assembler 
language macro instructions in the IBM Time Sharing 
System (TSS). The intended audience is nonprivileged 
assembler language users. 

The primary macro instruction services are program 
management and data management. These macro 
instructions facilitate TSS application programming. 

The first section describes the macro instructions by 
functional groups, enabling the user to select macro 
instructions needed to manage programs {manage virtual 
storage, load and link modules, handle interruptions, 
transfer to command mode, use SYSIN/SYSOUT and the 
system log, communicate with the operator, maintain 
timers, and create commands) and to manage data 
Idefine, connect, access, manipulate, disconnect, or 
remove data sets). The second section lists the macro 
instructions alphabetically and provides the information 
needed to code the macro instructions. Appendixes 
describe exit lists, synchronous error exits, end-of-data 
processing, machine control characters, linkage conven- 
tions, DCB fields, the DDEF macro instruction, the 
generation of literals by macro instructions, interruption 
handling, the TSS Macro and Copy library, data set 
sharing, the OPEN/CLOSE generated parameter list, and 
the conditional assembly of macro instructions. 

PREREQUiSiTE PUBUCATiONS 

The reader should be familiar with the information 
presented in the publications: 

IBM Time Sharing System: 

Concepts and Facilities, GC28-2003 
Assembler Language, GC28-2000 
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rREiACE 



This publication contains a description 
of the IBK Time Sharing System (TSS) macro 
instructions a¥ailable to the nonprivileged 
assembler language user. 

I'he publication is divided as follows: 



Appendixes -- explains the use of exit 
routines, control characters available wi ' 
certain data management facilities and ii 
terruption handling routines, and the con- 
ditional assembly of macro instructions. 



tart. I: Kacro Instruction Services - 
contains a summary of the macro instruc- 
tions arranged into functional categories. 
Following a brief summary of the catego- 
ries. Section 1 describes the data manage- 
ment services and Section 2 describes the 
prograa iLanagement services of TSS. 

Part II: Macro Instructions - provides 

descriptions of the TSS macro instructions, 
Section 1 shows how the macro instructions 
are described and defines the terms and 
symbols used in the macro instruction 
descriptions. Section 2 includes the de- 
tailed descriptions of the macro instruc- 
tions, arranged alphabetically; the TAMII 
itacro instructions are described in Appen- 
dix K. 



PE EEEQUISITE TSS PU5LICATIQHS : 



C oncep t s and F aci l ities y GC2B-2003 



A ssembler Language , GC28-20 00 



Other recommended TSS publications are: 

C omman d Syste m User 's Guid e , 
GC28-2001 

A ssemb l er Pro g rammer's Guide , 
GC28-2032 



Seireath Edition. (August 1976) 
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dition of new macros for handling virtaal storage segments. 

These macros are as follows: 

ESfSEG — Eeserve Segment Group 
DISCSEG — Disconnect Segment Group 
RELSEG — Release Beserved Segment Group 
DELSEG — Delete Disconnected Segment Group 
CONSEG — Connect Disconnected Segment Group 

Other technical changes are: 

A new operand has be&i added to the GETBAIi macro. 

New interruption codes for the SPEC macro have been 
added to indicate monitor call and program event 

recording. 

h change in return codes for the GATED macro. 

A new parameter for the SAIC and SIEC macros. 

This edition is current with Release 2.0 of the IBR Time 
Sharing Systeis/370 (TSS/370) , and remains in effect for all 
siibsegaent versions or modifications unless otherwise noted. 
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PAST 1: HACRO IMS TRU CIIQN S5R?ICES 



SEC T ION 1: OVERVIEW OF SERVICES 

Ine TS£ isacro instructioiis provide t<#o basic services: lata set man- 
agement anC Brooram nanagement. These s<^rviceE are sumiaarized below. 

TSS proYid3s data lianaqeaent macro instructions that: 

• I^eiine a d a ta set -- by introducing it to a task, describino its 
characteristics or attributes, such as its name, organization, dis- 
position, (that is, OLD or 'I^WJ , ana cataloaing it by name. After 

the data set Las been connected to the systero, TSS refers to the 
attribates to determine the access method and control information. 

• Connect a da ta set -~ by making its attributes available to the sys- 
tem in the data control block (DOB) . Appropriate access method rou- 
tines are initialized, labels are processed, and the data set is 
Dositioned for user processina. 

• Access a data set -- by using the macro instructions associated with 
the appropriate ?A*1 or SAW a.ccers method, or by providing user- 
written, iat>ut/outi>at davica-manaaeE^nt routines with the lOREQ 

sacro instruction. 

• Manipulate a iata set -- by transferring it, rather than individual 
records within a data set, from one area of virtual storaae to 
another, or to punched cards, printed listings, or magnetic taoe. 

• Disconnect a data se t — by tellina the system that a user has 
finished processing the data set an J, permanently or temoorarily, 
disconnectinq from the systeia the DCB containincr the description of 
the data set attributes and access-B.ethod specifications. 

• Pemove a dat a se t — by physically erasing it and releasing the 
storage in which it was recorded. 

TSS 'Orovides orogram manageaent macro instructions that: 

• Manage vir tu al storage — by acquiring or releasing pages or mul- 
tiples of eight bytes, or by transforming contiguous virtual storage 
bytes into an object module that is a single control section. 

• Load and link a module — by erplicitly or implicitly loadina object 
modules and establishing standard linkage between the calling and 
the called modules. 

• iian -ile interrupt ions -- by assuming cojitrcl of si>ecific types of 
interruDtions and executing user-written interruption-servicing rou- 
tines, instead of system-supplied routines. 

• I'ransfer t o command mode — by interrupting a prooram's execution, 
temporarily or perraanently, and passing control to command mode for 
further processing. 

• Communicate with SYSIH/SYSOUT — by passing data, messages, and com- 
mands between a coded program and SYSIH/SYSOOT devices. 

• Communicate with operator and log — by passing messages, issued 
during a program's execution, to the system operator and by record- 
ing them in his log. 

Part 1: Macro Instruction Services 1 
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• MaJ Rt ai'n t im ers — by setting thea to measure the time of a tas\"s 
execution or the elapsed calendar time. 

• Create coMiEands — by specifyipa user-written commands to te isFued 
instead of, or in addition to, systera-sapolieci commands, 

I • 'Jse s ystem- oriented liacro instructions — by employing those that 
I are intended primarily for system Drogrammers, but which are availa- 
I ble to all users. 

I The macro instructions by which these services ar^* recuested are sub- 

I seguently discussed. Section 2 i>rovides a general description of each 
f of tne functional groups and a brief descriotion of the function pro- 
vided by each macro instruction. Part II of this publication contains 
the detailed description of each macro instruction - 



This section describes the TSS macro instructions that are available 
to the user for managing data sets; they are presented in functional 
I groups that reflect their primary use in the system. Detailed explana- 
f tions of these macro instructions are Presented in Part II, Section 2, 
I "Macro Instruction Descriptions." 

I DATA SET SPECIFICATIOM MACROS 

Certain characteristics of a data set aust be described to the TSS 
routines for data set task management before a user can use these facil- 
ities to process and manipulate his data sets. These data set attri- 
Dutes can be furnished to the system by from two-to-six sources, depend- 
ing on whether a data set is new or one that has been previously defined 
to the system. The sources and their priorities are described in Appen- 
dix F. The two fiajor sources, and the only mandatory sources, used to 
describe these data sets to the system are the DDEf and DOB macro 
instructions. 

Attributes in a data set description are automatically cataloged when 
a public or private virtual access method (VAM) data set is opened. For 
sequential access method (SAP) data sets, however, the user must request 
that such attributes be recorded in the catalog by issuing a C^iT macro 
instruction, which can also be used to rename VAM or SAH data sets and 
to alter catalog entries for SAK data sets. These entries can be 
deleted from a user catalog by the DEL macro instruction. 

DDEF invokes the DBFF command processor to provide the connec- 
tion between a program and a data set. 

ODD calls the DDEF command processor with one or more DDEF com- 
mands obtained from a line data set. 

FIHDDS locates the JFCB corresponding to a given data set name, 
and optionally creates a JFCB (invokes DDEF) if the data 
set name is in the catalog. 

FIMDJFCB locates the JFCB corresponding to a given DDHAME, and 
optionally creates a JFCB (invokes DDEF) . 

CAT invokes the CATALOG command processor to catalog data sets, 
rename data sets, or create generation data groups. 
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EEL invokes the RELEASE command processor to dispose of the 
specified JFCB^ freeing the symbolic aame of the corre- 
sponding DDEP statement for other ase. Devices used for 
data sets on private volumes are optionally released for 
general use. PELBASE is used to free data sets from conca- 
tenation and to close and remove data sets from the job li- 
brary chain. A RELEASE of the symbolic name of the DDEF 
statement associated with an open data set results in that 
data set being closed. Any programs loaded from a job li- 
brary are unloaded by releasing a job library. 

DEL invokes the DELETE command processor to remove data set 
names from the catalog. 

DCB defines storage for a data control block. 

DCBD generates a dummy control section (DSECT) to d^cribe the 
DCB with names having the auprooriate attributes for DCB 
fields . 



I DATA CONTROL BLOCK PROCESSING lACROS 

Before processing a lata set, a user must connect it to the system. 
The OPE!l macro instruction causes the system to interrogate for the data 
set attribute information specified by the DDEF and DCB macro instruc- 
tions or any other available sources. The system determines whether an 
appropriate data set organization has been specified and whether all the 
necessary attributes for processing such a data set have been provided. 
If the user has indicated that he wants to alter the DCB contents during 
OPES processing, by including the EXLST parameter (for BEAM and QSAM 
only) with his attribute specifications, the system immediately exits to 
the aser noiif ication routine. When all the required attributes have 
been provided, all new ¥A!- data sets, public or Brivate, are automati- 
cally created and cataloaed (any new or uncataloged SAM data sets must 
be cataloged via the CAT macro instruction) . For previously cataloged 
¥AK data sets, the system uses attribute specifications recorded in the 
catalog. Any storage requirenents indicated by a DDEF space parameter 
are then allocated accordinaly. The system then makes available the 
access method that the user indicated he wants to employ (via attribute 
specification), thereby logically connecting hiia to the system - 

At the time a user opens a data set, he can select or default a proc- 
essing option that indicates to the system the type of processing he 
I expects to perform on that lata set. The processing option soecified 
I when the user issues the OPEN aacro instruction determines whether all 
the macro facilities of an access methoc or only a portion of them can 
be used- If a user opens a data set for input only, he will only be al- 
lowed to use macro instructions that retrieve data; he will not be al- 
iowei to use those that store data into the lata set he has otened. 

Once the system knows the Drocessinq option and locates the device on 
which a data set is to reside, or currently resides, it proceeds to 
physically open that data set by processing labels and physically posi- 
tioning the user at the data record he wants to process. "The initial 

positioning directed by the system varies depending on -the access meth- 
od, the processing option, ievice type, and in some cases the status 
(that is, -^OD) of the data set. 

j D?^2N collects tiie attributes of soecified data sets from various 
I sources, by prioritv, and meraes the information in the 

I respective DC3s. OPEM prepares a DCB and the data set as- 

I sociated with it for processing. 

Part 1: I'acro Instruction Services 3 
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CLOSE reverses the action of OPEM. CLOSE waits until I/O re- 
quests are complete before proceeding. When appropriate, 
output data set trailer labels are processed and access to 
volumes is positioned as specified. Control blocks^ such 
as the BCB and JFCB^ are restored to their original condi- 
tion. CLOSE disconnects a data set from further processing 
and user access. For BSHH and ?IK DCBs there is a CLOSE 
option that causes the same processing as the standard 
CLOSE macro except that fields of the DCB are not restored 
to their status before OPEM; the DCBs are in effect open 
and additional processing aay be performed. Hith 3S%M data 
sets,, temporary close is useful for repositioning a volume 
for subsequent processing and serves the purpose of com- 
pleting the data set (if it has 3ust been written or ex- 
tended) . In the case of VJkM data sets, temporary close 
causes the DSCBs to be written which captures the current 
status of the data set on external storage. 

I ACCESS KETHOD KACROS 

When a data set has been given a name^ nheii its attributes have been 
described, and when it has teen connected to the system, the user can 
employ the routines provided by the TSS data set management facilities 
for storing and retrieving data. Ihese routines are called by using I/O 
macro instructions in the user's source program. The macro instructioi^s 
are part of an access method and are deoendent on the manner in which a 
user organizes and processes his data. There are two primary types of 
access method: virtual access method (VAM) and seouential access method 
(SIH) . 

MI- 
I These are the access methods used in TSS • Data sets that must be 
I interchanged with programs running under the OS or OS/VS Program- 
ming System, or data sets to be written on magnetic taoe shouli be 
accessed using SAK. 

Users create, read, and process VAM data sets on the basis of log- 
ical records. The system, however, blocks these records ty paaes 
(4096 bytes) ; the oage is the unit of transfer between the direct 
access device and the user's virtual storage. The system also 
ensures that only those pages of a data set actually required are 
resident in virtual storage. Because ?Af data sets can be 
organized as either sequential, index sequential, or partitioned, 
three distinct access methods are Droviied under vak for data set 
processing : 

Da ta Set Organiz ation Access M etho d 

sequential virtual sequential (VSI^F) 

index sequential virtual index sequential (VISAH) 

partitioned virtual partitioned (V^Af) 

SAW: 

These are the access methods used for records that can be read and 
I written with programs running under control of the OS or OS/VS Pro- 
f gramming System, or when the data set is to be written on inagnetic 

tape . 

Users create, read, and process SAM data sets on the basis of phys- 
ical records. The records within a physical record can te blocked 
or unblocked. Because of this, two access methods are orovided un- 
der SAM for processing data sets: 
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Data Set. Orqanizatio ri Acce s s Eetho d 
unblocked seguenrial basic sequential (BSAM) 
blocked sequential oueued sequential (QSAP) 



Another special access facility, the input/output request facility 
(lOREQ) is provided for users who would rather orograit their own I/O 
device-control routines than employ any of the system-provided access 
methods . 

Explanations of each of these access methods, and the macro instruc- 
tions that may be used with them, follow. 

Virtual Sequential Access M ethod 

The virtual secuential access iiethoi (VSAM) enables a user to process 
virtual sequential data sets. These data sets can be stored on, or 
retrieved from, direct access devices only. The record fori^at within 
each such data set may be f ixei-lenqth (blocked or unblocked) , variable- 
lenqth (blocked or unblocked) , or undefined-length (unblocked only) . 
Such attributes are unicrue for each data set; they must be defined to 
the system before a data set can be accessed by VSAM. 

GET reads logical records in seauential order. 

PUT writes logical records in sequential order. 

PUTX replaces a logical record, Previously read by GK? - 

SET! logically positions access to a data set at the beoinnincr 
or end, at the previous record, or at any logical record 
within a sequential data set. Subsequent PUT or GET opera- 
tions will proceed from this new position. 

Virtual Ind ex Sequen tial A c cess 'i ethod 

The virtual index seauential access method (VISAK) enables a user to 
process index sequential data sets. These ^ata sets may be stored on, 
or retrieved froa, direct access devices only. The record format within 
each such data set may be fixed-length (blocked or unblocked) or 
variable-length (blocked or unblocked) format. Such attributes are 
unique for each data set; they must be defined to the system before a 
data set can be accessed by VISA*!. 

GET reads logical records in sequential order, by key - 

PUT writes logical records in seouential order, by key. 

READ reads logical records in nonsecruential or sequential order. 

liRITE writes logical records in nonsequential or sequential 
order. 

DELKEC deletes a specified logical record from a data set. 

SETL logically positions access to a data set at its beginning 
at the previous record, or at any logical record. Subse- 
quent PUT or GET operations will proceed from this new 
position. 

ESBTL releases a read-lock set by other operations. 

RELEX releases a write-lock set by other operations . 



Part 1: Macro Instruction Services 
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'ULL M:i _i^ a-t t it i o ned. Access Method 

The virtual partitioned access method (V?AW) enables a user to access 

l>arti-LioB.er: data sets. Each Bartitione^ segment (or member) is a com- 
plete VSAM or VISAH lata set. The organizations of the records within 
members are the same as within VSAF or VISAF. VPAF may be used only to 

store or retrieve lata set aenbers on iirect access devices. 

In hen a partitioned data ser has been defined and connected to the 
system, the user may employ the ¥?1M macro instructions (FI1D and STOW) 
to locate xts meEbers- Bhen the lember is opened and located via a FISD 
macro instruction, the ¥SAr or ¥ISA!! macro instructions can be used to 
process the meiiber- Although a raember is defined by the same DDEF and 
DCB ikacro instructions that defined the partitioned data set, the member 
is not opened until a ¥PAM FIMD macro instruction is executed. 



IIND 



opens an individual meaber within a VPA1 data set for proc- 
essing. After FOB, appropriate VISAM or VSAM macros can 
be used to process the records within the member. 



STOi causes a VISAM or VSAM member of a partitioned data set to 
be added to or deleted from the data set. It also adds, 
changes, deletes, or replaces member names or aliases, and 
provides for storing additional information in the parti- 
tioned organization directory C^OD) , as user data. 

Basic Seauential Access Method 
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READ reads a physical record from an I/O device and specifies or 
defines a data event control block (DECB) to be used to in- 
dicate completion status for the operation. After BEAD, 
control is returned to the user program. The user program 
is responsible for deblocking logical records from physical 
records - 

WPITE is the same as HEAD exceot that data transfer is in the 
opposite direction. 

CHECK tests the gueue of DECBs associated with READ or WRITE op- 
erations to determine if the operations are complete and if 
so, whether errors or exceptional conditions occurred. 

bQDECB removes all unchecked DECBs associated with READ and IRITE 
operations for a specified device. DQDECB is used when 
restarting I/O after user program action on error 

conditions. 

HOTE makes available to the program, for use with POINT, the 

relative position within a volume of the last block read or 

written. 



POINT repositions access to a data set at a specified block with- 
in the data set. 



BSP 
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backspaces one physical record or block on the current tape 
or direct-access volume regardless of the direction in 
which data is being stored or retrieved on that device. 



CNTEL controls tape positioning and writing of tape marks. CHTHL 
can be used to obtain sense data from tape or direct-access 
devices. 

FEO? positions access to the data set at the next volume of a 
multivolume set. 

GETPOOL requests allocation of virtual storage for use as a buffer 
pool and assigns that area to a DCB. 

GETBUF obtains a buffer work area from a buffer pool previously 

assigned to a DCB either by a GETPOOL macro or as provided 
according to DCB buffer options. 



FIEEBOF 



PREEPOOL 



returns a buffer work area obtained by GETBOF to the 
related buffer pool. 

releases areas previously assigned to specified DCBs as 
buffer pools either by a GETPOOL macro or as a result of 
buffer options specified in the DCB. 



Q ueued Sequent ia l Access M e thod 

ihe queued sequential access method (QS 
blocked or unblocked physical sequential d 
to BSAK, permits the programmer to store a 
sequential data set without coding his own 
ering routines. A sequential data set can 
from, disk or tape. The record format wit 
fixed-length (blocked or unblocked) , varia 
unblocked) , or undefined-length (unblocked 
unique for each data set; they must be def 
data set can be accessed by QSAM . 



AM) enables a user to access 
ata sets. QSAM, in contrast 
nd retrieve records of a 
blocking/deblocking and buff- 
be stored on, or retrieved 
hin each such data set can be 
ble-length (blocked or 

only) . Such attributes are 
ined to the system before a 



GET 



RELSE 



reads logical records in seauential order. The initial GET 
causes a physical record from the input device to be trans- 
ferred to a system-maintainal buffer area and makes the 
first logical record available to the user progran. Each 
subsequent GET delivers logical records uFi til all logical 
records within the physical recorl have been processed. 
Keanwhile, the next physical block is transferred. 

causes the remaining records of the current input buffer to 
be ignored and positions access to the data set at the 
first logical recx>rd of the next physical record. The next 
GST macro will retrieve the first logical record from the 
new input buffer. 



PUT 



is the same as GET except that data transfer is ir the 
ooposite direction. 



PUTX replaces a logical record, oreviously read by GET, or 

writes an updated or identical loaical record directly froir 
an input data set to an output data set- 

TEUNC causes the current output buffer to be regarded as if it 
were filled. The output buffer is written to the output 
device, leavina access to the data set Dositioned at the 
next buffer area. The next PUT issued is for the first 
record of the next block. 



Part 1: Macro Instruction Services 



PageofGC28-2004-6 
Revised 9 May 1979 
By TNL GN20-3941 

SETL logicallf positions access to a data set at its beginning 
or end, at the previous record^ or at anj logical record. 
Siibsegnent PUT or GET operations will proceed from this new 
position. 

CNTEL controls tape positioning and writing of tape marks.. CHTSL 
can be used to obtain sense data from tape or direct-access 
devices - 

f Inpat/Oatput Request Access Metho d 

The input/output request facility (lOEEO) enables users to program 
their own I/O device-control routines , rather than use those from ?A1 or 
SAM. lOREQ provides a means to control I/O devices through user speci- 
fication of channel command words (CCWs) that are normally created by 
the TSS-supplied access methods. Using I0B2Q, the user can create a se- 
ries of these channel instructions and execute them as he desires. The 
lOREQ, CHECK, and VCC» macro instructions enable users to create their 
own specialized access methods. 

As with provided access methods, before the lOEEQ facilities can be 
used to access a data set, the data set must be described and connected 
to the system and, when the user has finished using the data set, it 
must be disconnected from the system. 

lOEEQ , initiates a reguest for an I/O operation specified by a 
user-written channel program and specifies or defines a 
data event control block (DECB) to be used to indicate com- 
pletion status for the operation- After lOREQ, control is 
returned to the user orogram. 

CHECK tests the crueue of DECBs associated with lOSEQ operations 
to determine if the operations are complete and if so, 
whether errors or exceptional conditions occurred. 

DQDEC3 removes all unchecked DECBs associated with lOREQ opera- 
tions to a specified device. DQDECB is used when restart- 
ing I/O after user proaraa action on error conditions. 

VCCW defines storage for a virtual channel command word (VCCi) . 
A ^CC"^ serves the saise function as a CCW . The format is 
rearranged to allow for the 3 2-bit addressing mode of the 
360/67. Cnains of one or more ¥CCWs specify I/O operations 

to be performed. 

I GOBI BhTl SET & BULK OUTPU't^ r?,CPOS 

Entire data sets can be transferred froa^ one storaae device- to anoth- 
er. A data set can be moved from one direct access device to another, 
or to a different area on the same iirect access device. They can also 
be copied to punched cards, printer listinas, or maanetic tape devices - 

Several macro instructions are provided with TSS to perforin these 

operations . 

A user may decide to include an existina data set in a partitioned 
data set, to renumber the lines of an existing line data set, or to 
store an existina data set on a different device, releasing the device 

I on which tne data set is stored. The COPYDS macro instruction lets a 

user accoiijplish these operations. 

The bulk-output facilities allow a user to transfer entire data sets 
from virtual storage to punched cards, printer listings, or magnetic 
taf»e devicfc^s- ihese facilities orovide a user with three macro instruc- 
tions, print (ir^B) , pur.ch (?U) , and write tape (WT) , to accomplish these 



transfers, ihese three macro instructions are to be issued in a user 
program on SAK^ VSAM and VISAK data sets only. Ilthouah VPAM data sets 
or members cannot employ these macro instructions, the members of the 
VPAM data set can first be copied with a COPYDS macro instruction (or 
command) into nev ¥SAK or ?ISA?t data sets and then be operated on by 
these macro instructions. Execution of these macro instructions causes 
requests for particular output operations to be set up as independent 
nonconversational tasks, places the requested task on a bulk output 
queue, and returns to the user's problem program. The user can then 
continue processing other data sets (or terminate his sessxon) while the 
output task is being executed. 

COPYDS invokes the CDS command processor to create copies of ex- 

isting data sets or members of partitioned data sets that 
have been previously defined to the system and reside on 
direct access or magnetic tape volumes. It also creates 
copies of line data sets with renumbered lines. The copies 
are placed in new data sets. The new data sets and the ex- 
isting old data sets must be previously defined to the sys- 
tem. The old data sets do not, however, need to be opened 
by the user; they are opened by the CDS command processor. 

PE invokes the PBINT command processor to list a specified 

data set on a high-speed, on-line punch and, optionally, 
erases it from the user's catalog when the printing has 
been finished. Line spacing on the printed output can also 
be indicated by the user- The print operation takes place 
as an independent nonconversational task. 

PU invokes the PUMCH command processor to cause a data set to 

be punched on-line and, optionally, erases ±z rrom the 
user's catalog when the punching is finished. Stacker 
selection can also be indicated by the user. The punch op- 
eration takes place as an independent nonconversational 
task . 

yiT invokes the WT command processor to cause a data set to be 

written on magnetic tape in proper format for subsequent 
off-line printing and, optionally, erases it from the 
user's catalog when the writing is finished. The write- 
tape operation takes place as an independent conversational 
task . 



ERASE DATA SET MACRO 

ERASE invokes the ERASE command processor to uncataloq and free 

the space occupied by direct-access data sets. 



S ECTION 3: PROGRAM MANAGEME |T 

This section describes TS S program management macro instructions. 
They are presented in functional groups that reflect their primary use 
in the system. 

Part 1: Macro Instruction Services 
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VIRTUAL STORAGE MAMAGEMEUT MACROS 



GETMIIK is used to acquire additional virtual storage. 

IREEMAIIfl releases virtual storage acquired with GETMAIM. 

CKCLS determines the most restrictive protection class assigned 
to a specified number of contiguous halfpages of virtual 
storage- 

CSTORE saves contiguous virtual storage areas in object module 
format . 

RS¥SEG associates a name with a contiguous set of virtual storage 
segments. 

DISCSEG disconnects a segment group from a virtual address space 
and assigns a name to it. 

CONSEG connects a disconnected segment group to an unassigned por- 
tion of a virtual address space. 

ESLSEG releases a reserved segment group, deleting the name, but 

leaving addressable the virtual address space of the group. 

DELSEG deletes a disconnected segment group. The name and any 
space on auxiliary storage are deleted. 

EXCSEG performs the COHSEG and DISCSEG macro instructions in one 
operation. 

GETSEG gets a paae from a disconnected segment group and places it 
in a buffer specified by the user. 

PUTSEG puts a page from a virtual storage buffer into an existing 
disconnected segment group. 

PROGRAM LINKAGE MACROS 

A user has two ways of requesting that a module be loaded into virtu- 
al storage: an implied request or an explicit request. An implied re- 
quest causes automatic loading of a program into a user^s virtual 
storage, during program assembly, each time the source program refers to 
(via the CALL macro instruction) an undefined external symbol. An 
explicit request is satisfied during the actual execution of the program 
containing the request. When the explicit request (via a CALL or LOAD 
macro instruction) is executed, the module referred to is loaded into 
virtual storage assigned to the user's task. 

Unlike the implicit call, the program loaded by an explicit call dur- 
ing program execution may be released by a DELETE macro instruction or 
an UNLOAD command. This releases the virtual storage area occupied by 
that program for other use- 

When a user •s program calls another program, either explicitly or 
implicitly, these programs establish linkage by using standard TSS lin- 
kage conventions. Thus, proper registers must be used in establishing 
linkage, and a save area must be set aside in the calling program- Two 
macro instructions (SAVE and RETURN) establish standard linkage. 

LOAD explicitly loads a program, if it is not already loaded, 

into virtual storage. The address at which the program has 
been loaded can be obtained from address constants previ- 



10 
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ously defined by an ADCON or ARM macro. The program 
remains in virtual storage until it is unloaded by a DELETE 
macro or an UNLOAD command. 

CALL explicitly or implicitly loads the called program into vir- 
tual storage and establishes conventional linkage between 
the calling and called program. The address at which the 
program has been loaded can be obtained from address con- 
stants previously defined by an ADCON or ARE macro. CALL 
causes control to be given to the called program - 

AEK initializes the address constant group defined by an ADCON 
macro with the name of the program^ entry point, or control 
section that is to be loaded into virtual storage . The 
initialized address constant group can subsequently be used 
by a CALL or LOAD macro to explicitly load the program. 

ADCON generates a group of address constants for use by CALL, 
LOAD, or DELETE macro instructions. 

ADCOND generates a DSECT to describe the address constant group 

with names having the appropriate attributes. These names 
make it possible for an assembler language program to ref- 
erence symbolically the resolved address constants and con- 
trol flags placed in the group during execution of a LOAD 
or explicit CALL macro- 

DELETE unloads an explicitly loaded program that is no longer 

needed, freeing virtual storage. Any associated programs 
are also deleted. 

SA¥E stores the contents of the general registers according to a 
standard convention. The SA¥£ macro is normally the first 
instruction in a called routine. 

REIURJi restores the contents of the general registers according to 
a standard convention and returns control to the calling 
routine, optionally setting a return code for the calling 
routine . 

MARKRTEN indicates to the calling program that the called program 
has returned- 

IMTERRUPT HANDLING MACROS 

TSS provides interruption -handling facilities that permit the user to 
control task interruptions- User-written routines can be invoked to 
service interruptions; these routines, which decide how to respond to 
each type of interruption, can ignore certain interruptions. 

SIR specifies a user interrupt routine (named via a SPEC, 3AEC, 

SIEC, SEEC, STEC, or SS EC macro, according to the type of 
interrupt) to the task monitor. SIR specifies the process- 
ing priorxty for that routine. The user's routine replaces 
any system-supplied interruption servicing routines for 
this type of interruption, unless the user's routine is 
deactivated with the DIR macro. System-supplied routines 
are reinstated after the user routines are deleted. 

DIE deletes an interruption servicing routine, reversing the 

effect of the corresponding SIR macro. 

SPEC names a user-written program interruption servicing routine 

and defines an interrupt control block (ICB) in which data 

Part 1: Kacro Instruction Services 11 
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pertaining to a program interruption can be recorded. The 
named routine v ill be used when it is defined to the task 
monitor as an interruption servicing routine by a SIE 
macro. 

SSEC names a user-written SVC interruption servicing routine and 
defines an ICB in which data pertaining to an SVC interrup- 
tion can be recorded. The named routine will be used when 
it is defined to the task monitor as an interruption serv- 
icing routine by a SIP macro. 

SEEC names a user-written external interruption servicing rou-- 
tine and defines an ICB in which data pertaining to an ex- 
ternal interruption can be recorded. The named routine 
will be used when it is defined to the task monitor as an 
interruption servicing routine by a SIE macro. 

SAEC names a user-written asynchronous interruption servicing 
routine and defines an 1C3 in which data pertaining to an 
asynchronous interruption can be recorded. The named rou- 
tine will be used when it is aefined to the task monitor as 
an interruption servicing routine by a SIR macro. 

STEC names a user-written timer interruption servicing routine 
and defines an IC3 in which data pertaining to a timer in- 
terruption can be recorded. The named routine will be used 
when it is defined to the task monitor as an interruption 
servicing routine by a SIF macro. 

SIEC names a user-written I/O interruption servicing routine and 
defines an 103 in which data pertaining to an I/O interrup- 
tion can be recorded. The named routine will be used when 
it is defined to the task monitor as an interruption serv- 
icing routine by a SIB macro. 

INTINQ inquires about the interruption information recorded in a 

specified ICB. Various options are available- Control can 
be relinquished until the ICB indicates an interrupt. If 
the interrupt has been oueued, the routine in which -^he 
INTINQ is issued may regain control immediately. Also^ the 
task can be made to wait until a corresponding interrupt 
has occurred- Interruptions cueued on the ICB can be 
cleared by INTINQ. k specified branch can be taken if the 
interrupt information is present. 

SAI saves the task's current interruption servicing status 

indicator and inhibits further interrupts until a RAE macro 
is issued. Interruptions occurring while the inhibit indi- 
cator is on are saved and queued for later servicing. 

EAE restores the interruption servicing status previously saved 
by an SAI macro. Depending on the saved status (enabled or 
inhibited), processing continues. If interrupts were pre- 
viously enabled ^ any interruptions that occurred while in- 
terruption servicing was inhibited are processed before 
processing continues. 

PIESC efficiently tests an address for validity. Program inter- 
rupt codes 4, 5, and 6 occurring when PIBEC is being 
executed are not processed in the normal manner. Detection 
of an invalid address results in a branch to a specified 
location . 

US ATT causes subseguent attention interruptions to be processed 
by a user-written routine that was previously established 
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as an interruption servicing routine by the SIR and SIEC 
macros. 

CLATT reverses the effect of a USATT macro. Control of attention 
interruptions obtained with a USATT macro is relinquished. 

AEID causes attention interruptions to be processed by any one 
of several user -written routines, depending on the number 
of times the attention key is pressed. The ASTD macro is 
also used to relinquish control of attention interruptions 
acquired by the AETD macro. 

COMMAND SYSTEM INTEBFACE MACROS 

TSS provides a user with several ways of interrupting a program's 
execution, either temporarily or permanently, and passing control to 
command mode for subseouent processing. 

BPKDS generates all necessary linkage information and parameter 
storage areas required for use during the execution of a 
command that was defined with the BUILTIH command. Also, 
information from the BPKDS expansion is used by the KEYWOPD 
command . 

GDV gets the value for a default from the task's combined 
dictionary. 

GETBV gets the value for a specified name and type from the 
task's combined dictionary. 

SETD? sets the value for a specified name and type into the 
task's combined dictionary. 

OBEY temporarily passes control to the command system tor execu- 
tion of a specified command. The command specified by OBEY 
will be issued just as if the user had interrupted the pro- 
gram and issued the command. When the command or a program 
invoked as a result of the command returns control to the 
command system, execution of the program from which the 
OBEY was issued will be resumed. 

PAUSE (for conversational tasks only) writes a user-specified 
message on SYSOUT and causes the task to enter command 
mode. A GO command causes execution of the program to 
resume. The interruption of a program by PAUSE is very 
similar to that which results from an attention interrupt. 
If the user has control of attention interruptions before 
issuing a PAUSE , the system regains control of them until a 
GO command is issued. PAUSE is ignored in a nonconversa- 
tional task. 

COMMANb is the same as PAUSE except that it is not ignored in non- 
conversational mode. The SlSll^ data set is read lor the 
next command. Execution of the interrupted program can be 
resumed with a GO command. 

CLIC is the same as the PAUSE macro except that no message is 
issued - 

CLIP is the same as the COKKAND macro except that no message is 
issued . 

EXIT is a simple way of terminating execution of a program and 
optionally causing a predefined system message and a user- 
Part 1: riacro Instruction Services 13 
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specified message to be written on SYSOUT, Control is re- 
turned to the command system and the next commands are 
taken from SYSIH. 

ABEND indicates an abnormal end condition to the user and the op- 

erator. The ABEND macro provides for various types of sys- 
tera action based on the severity code specified. Codes 
are: (1) Terminate execution of the program, returning 
control to SYSIN for conversational tasks; for nonconversa- 
tional tasks either delete the task from the system or 
switch SYSIN to a data set defined with a DDNAMS of TSKA- 
BEND- (2) Terminate the task, creating a new task if the 
old task was conversational. (3) Terminate the task, do 
not create a new task. (4) Terminate the task without 
attempts to write to SYSOUT. (Used by privileged programs 
only.) A message may be specified with the ABUKD macro, 
either as the actual message or as the identification code 
of a message in the system or user message file. 

SYSIN/SYSOUT COMMUNICATION MACROS 

The TSS communication facilities permit a user to pass data, mes- 
sages, and commands, to and from a user's SYSIN and SYSOUT devices. 

GATED reads a record from SYSIN and places it in a user- 

designated virtual storage area. 

TGATRD extended function form of GATRD macro. 

SOLICIT presents a continuously incremented number as a prompt to 

TGATED operations. 

GATWR writes a record on SYSOUT. 

TGATWIi extended function form of GATWR macro. 

TGATWS writes a record on the primary SYSOUT. 

TREAD reads (transparent) a device dependent record. 

TWRITE writes (transparent) a device dependent record. 

TWRTLST writes records from a list of virtual storage areas to 

SYSOUT. 

GTiRC writes a record on SYSOUT. The first byte of the record is 

used for carriage control when printing nonconversational 
SYSOUTs . Carriage control action is approximated for con- 
versational tasks. 

GTWAR writes a record on SYSOUT and reads the next available rec- 

ord from SYSIN and places it in a user-designated virtual 
storage area. 

TGTI^AR extended function form of GTWAR macro. If input buffering 

is in effect, the write operation is suppressed. 

GTWSR writes a record on SYSOUT and reads the response to that 

record, placing it in a user-designated virtual storage ar- 
ea- If issued in a nonconversational task, unless the user 
has indicated otherwise, the task will be terminated. 

TGTWSR extended function form of GTWSR macro. If input buffering 

is in effect, the write operation is performed immediately 
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and the read operation in response to that write is per- 
formed immediately. 

SYSm optionally writes a record on SYSOUT and reads a record 

from SYSIN into virtual storage. If the record is recoq- 
nized as a commandr it is placed in the source list for 
subsequent processing by the command analyzer. User pro- 
grams can detect the incidence of commands and take action 
accordingly. Otherwise, the user program is interrupted 
and the command is processed. 

TCNTRL specifies miscellaneous control operations. 

CHCKT checks the status of a DECB related to SYSIN/SYSOUT 

operations. 

TBCBUF reads a record from the conversational buffer for the ter- 

minal and places it in a user-designated virtual storage 
area. 

TDCHD issues device control commands from user programs to con- 

trol the terminal environment. 

TCLEAE purges any pending or active request buffers on 

SIS IN/SYS OUT. 

TFREE disconnects a secondary SYSIN/SYSOUl from the task. 

MCAST temporarily substitutes a user-specified character transla- 

tion table and function control table. The character 
translation table specifies substitution of character codes 
for transfer of data between user progjcams and SYSIN and 
SYSOUT. The function control table identifies characters 
which are to have special effects, for example backspace to 
mean overstrike, not character correction. 

ATTNSAV saves current conditions (buffers and terminal environment) 

in a pushdown stack. 

UTTNRST restores previously saved conditions and buffers, disposing 

of the current conditions. 

ATTNDST disposes of saved conditions and buffers no longer needed. 

PRMPT invokes a system facility which prompts the user with mes- 

sages from the system message file, if not from the user 
message file- The prompter analyzes responses to messages 
whose coding indicates that a response is required. 

OPERATOR S SYSTEFi LOG COKKUUi ICATION KACROS 

The TSS communication facilities provide macro instructions for user- 
communication with the main operator's terminal and with the system log 
(a generation data group, in which each VSAK data set contains a record 
of system-to-operator and operator-to-systen communications, from 
startup-to-shutdown) - These routines should normally be used only for 
programs having specialized 1/0 routines that require operator 
intervention . 

WTO writes a user-specified messacre on the operator's console. 

WTOA writes a user -specif led action message on the operator's 

console. Action messages differ from those sent by WTO in 
that they are prefixed by characters intended to catch the 
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operator's eye. They should only be used when action is 
required by the operator, otherwise the operator may disre- 
gard the action message format. 

WTOE writes a user -specified message on the operator's console. 

The user task waits for the operator to respond to the mes- 
sage. The operator is periodically reminded of unanswered 
messages. The reply from the operator is made available to 
the program. It the operator fails to reply within a rea- 
sonable timer the user can use the attention key to regain 
control and decide on some other course of action . 

WTL causes a user-specif ied message to be written in the system 

log data set. If the operator wishes to have WTL messages 
appear on the console, a default can be set in the combined 
dictionary of the operator USERID. 



IIHER KAINTENANCE KACROS 

TSS requires maintenance of elapsed-time and resource-usage statis- 
tics. The user needs the facility to set a timer that will measure his 
task's execution time or the elaosed calendar time- Each task has eight 
interval timers associated exclusively with that task that are access- 
ible to the user. 

STIKER sets a software interval timer, measuring either task 

execution time or real time, and indicates what action 
should be taken when that specified time interval has 
elapsed . 

TTIttER tests an interval timer previously set by the STIKER macro 

and indicates the time remaining in that interval. It can 
also be used to cancel a previously specified timer 
setting . 

REDTIM provides time as a double precision, fixed-point number in 

microseconds. In TSS the epoch is Karch 1, 1900. 

EBCDTItlE converts system -maintained time into specified EBCDIC for- 
mats- The time is expressed in some combination of years, 
months, days, hours, minutes, seconds, tenths of seconds, 
and hundredths of seconds. 



SYSTEM ORIENTED MACROS 

In addition to those system-oriented user macro instructions already 
indicated within the various functional groupings, several other such 
macro instructions are available: 

AWAIT tests for completion of an event and returns control to the 

task it the event is completed, or places the task in a 
delay state from which it will be removed when any task in- 
terruption occurs. 

?SEND sends a message from one task to another. The message is 

queued on the recipient task status index fTSI) as an ex- 
ternal interrupt- 

USAGS causes resource statistics for a task to be made available 

for processing by a user program. 
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XTRTK extracts and examines the total accumulated CPU time of the 
issuing task from the extended task status index (XTSI) of 
the task. 

HASH provides a hash value for a name. 

LPCEDIT invokes the editor, which can be used by a language proces- 
sor controller for input of source statements. 

LPCIKIT identifies the program vhich issues it as a language pro- 
cessor controller and initializes the editor for later use. 

LIBESBCH determines if a specified object module is to be found in 
any of the job libraries and if so, which library. 

CEDEErtIC generates messages pertaining to errors encountered during 
macro expansion . 

CHDVIL determines the type code of a parameter during macro 
expansion . 

CHDPSECT changes the name of the current control section of an 

assembly to the name of the first PSECT for that assembly. 
If no PSECT exists, a branch to a specified location is 
generated, either as the actual message or as the identi- 
fication code of a message in the system or user message 
file. 

I ENQ requests exclusive/shared read only access to a resource. 

I DEQ releases a previously issued resource access request. 
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PART 2: HACRQ INSTHUCTIONS 



This part describes the nacro instructions supplied with TSS that are 
available to all users. Secrtion 1 tells how they are lescribed: section 
2 describes the macro instructions, arranged alphabetically. 

I The aacro definitions for the macro instructions in this book can be 
I primarily found in the system lata set TSS***** .SYSMAC; a few are in 
I TSS»****.IS?1!!AC. 

SECTION 1: HO^ MACEO USTSOCTIOHS ARE DESCRISE D 

First, for a basic underrtandino -of how macro instructions in this 
book are described, look at Fiqure 2. This fiqure la? also serve as a 
quick reference whan reading the description of a macro instruction. 
You may wish to tab it. 

The information that follows suoDlements Fiqure 2. 

MACHO I!iSrauCT10!l iORMAT 

Kacro instructions, like assembler instructions, are written in this 
format: 

I 1 ' 1 1 r 

INaae |Opera tion | Ooerand IComment | 

I 1 1 1 1 

III I t 

I 1 I i I 

Name Field 

The name field of the macro instruction ma? contain a symbol or may 
be blank. Normally, the synbol is the name associated with the firsr 
executable instruction of the macro expansion. 

Op erat i on Fiel d 

This field contains the mneaoaic operation code of the nacro instruc- 
tion. Tne code may be a string of not riore than eight alpnaieric char- 
acters, the first of which is ilpha.fc9t:ic. 

Op erand Field 

This field may contain no ooerandr, or one or more operands separated 
by commas; the two types of operands are positional and keyword. Blanks 
may not be imbedded between ooeranls. 

Comstent Field 

This fielJ is separated from the op*=*rand field by at least one blank. 
Comments nay contain all valid characters in the cha^^acter set, includ- 
ina blanks. In statements where an optional operand entry is oiittei, 
or in statements which allow no operand but in which a commeiit entry ir 
to pe usei, the abseacp of the operand errtrv is indicated by a comma 
preceded anl followei bv one or more blanks- In this publication, th^ 
comments field is not shown in the macro instruction formats. 
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;fttAWl.fS OF OPERAhJO FORMS Operand formi not exploined here are deicribed in the ftdividual ftwcro deirriptioni. 



REOr^TFR ri'-'t.-ir fi (2) 

or fR?) 
* tfw fnforrtiotlon to be provided has first been 
d into reciifter 2 ond R2 hnt bewn equoted to 2, 

otherwise jtoted, r»gtin-i 2 through 12 may 
tcified. 

» ABSoane rxfPfv-.i' tj. k) 

: . ■ or TEN 4 FOUR 

or SAM - JOE 
whmr« TEN ond FOUR have been equoted to tO ond 4; 
wH*ni SAM onef JOE ore reiocntablA termi, 

. PFIOCATARIF FxPRF^SH'tJ CZCAT1 

or CZCATt+4 
vyKere CZCATl !« the nonie of a field ifiof may be 
rebcoHtd within vIr»ijol storage. A relocotoble 
•xonmlor^ con fbut iwiM not nece«ar!lyl be 
mode the symbol in on oddrew con«tont. 



. Rx AnnRFss. 2(0,S) 

where 2 is the ditptacemant, is the index 
register, ond 5 h the bose regiiter. 

MAUD 
or MAUD nt 

where the b<jst i^giiter is implied, 1 (in the 
second exewple) ii <sn Index itsgijttf, ond the 
lortition counter volue of MAUD li the 
ditplacement. 

, NUMBER. 45 

or 3C (b«.0tfeelmal| 
Unl«i itoted otherwlie, a deeimol integer li Implied. 

• TEXT: 'THIS ISA MESSAGE' 

A string of cboroetert enclosed by single opostrophe*. 
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. CHARACTER SIRING- %CR'554AQ^ 

A string of chorocfers contoininq »w imbedded com-nos 
or blenki ond not beginning or end'ng with an opostrapb 

> SYMBOL: START 

C2ATJT 

ONE 
A special form of chorocter string aeceptoble in the 
nome field of an ossembler itotement; \ to 8 alphameric 
rharorters (O-O, A-7, plus $, • , and *) with fin' 
chornftPr olpbobefic. 

RATA qri NAMF 



Figure 2. how to en*»r nacro inptructiuns 



POSCTIOKMi OPERjyglDS g Positional operands are tlK^se tbat must: be lirit-ten 
in a specific position within tte operand field. AssgiiiIdIy processing of 
positional operands is determined by the position they are aessigned in 
the operand f ield« The positions of the operands are maintained by the 
separating oonimasi if an operand is omitted, the coiriEa must nev'ertbeless 
be supplied to maintain the position of succeeding operands. For 
example: 

operl,oper2 «oper3 

The three operands are processed in order from left to right. If the 
second operand is omitted, the operands are written; 

operl,,oper3 

If the last positional operand or operands are omitted, delimiting ccmb- 
mas need not be written- For example, if operands oper2 and oper3 are 
omitted, the operand field may be writteas 

operl 

KiyiiOlID OPERMIDS ; A keyword operand consists of a keyword, immediately 
followed by an equal sign and the value of the keyword. The keyword 
uniquely identifies the operand to the assembler; these operands may 
therefore be written in any sequence. Either 

BI3FNO=20 ,BtJFIi=132 

or BI1I1,=132,BUFNO=20 

may be written. 

If keyword operands are omitted, their separating commas may also be 
omitted. 

MIXED OFERAIIDS s hM Operand field may contain both positional and ki^* 
word operands! in this case, all positional operands must precede any 
keyword operands. 

132, 20,NA,KEY=A,CODE«liT 

OMITTIliG OFERANDS FROM MIXED OFERAliD FIELDS s The rules for omitting 
positional or keyword operands apply to mixed fields. In the example 
immediately above, if operands 20, NA, and KEl are omitted: 

132,CODE=NT 

If operands 132 and CODE are c^nitted: 

,20,liA,KEy=A 

OPERAHD SDBLISTS : An operai^ sublist consists of one or more positional 
operands, separated 1:^ commas i the total list must be enclose in paren- 
theses. The entire string is considered as one operand in that it occu- 
pies a single position in the operand field or is associated with a 
single keyword. The contents of the string are processed in the same 
way as positional operands.. These are operand sublists: 

CA,B,C) 
(A) 

Note that sublist CA> consists of only one operand. Hhen a macro in- 
struction description shows that even one operand is written as an 
operand string, the enclosing parentheses must be written. 
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OPERAND STRINGS : In a number of macro instruction descriptions in this 
publication^ the operand fields except perhaps for the operand speci- 
fying the macro form (MF) , consists of a list of keyword and/or posi- 
tional operands that are written as fields of a character string. The 
character string itself, enclosed in apostrophes, or the address of the 
string in storage, may be written in the operand field. The manner in 
which the address may be specified may depend upon the macro form. 

If the operand is presented as a character string, the macro expan- 
sion places it in the assembled program followed by an end-of -message 
code, and loads a pointer to the string in register 1. If the operand 
field specifies the address of the character string, the expansion 
places that address in register 1. In the latter case, the user must 
define the operands elsewhere in the program and provide an end-of- 
message code. 

If the user wishes to refer to and manipulate the operands in an 
operand string in coding, the address option of the operand is used, 
permitting the operand character string to be set up as a series of 
adjacent fields, each with its own label. 

©le string must end with X"27*, which serves as an end-of -mess age 
code. Any \inused space in each of the adjacent fields in the string 
must be filled with blanks to the maximum size of that field. Unlike 
other operand forms, all commas in an oplist operand must be coded, even 
if parameters are defaulted. EXl and EX2 show how each of the string 
and address options for the operand field are used? the two examples 
have the same effect. 

EXl MACRO 'first operand, second operand* 
EX2 MACRO STRING 



STRING CC C" first operand" 
OP 2 DC C" second operaiKi* 



BC X«27 



Macro Description Notational Symbols ; Notaticnal symbols in the operand 
field of macro instruction descriptions assist the user in showing how, 
when, and where an operand should be written i these symbols are them- 
selves never written in the operand field. The notational symbols ares 
vertical stroke, |j hyphen, -j braces, { Ij brackets, [ 1; ellipsis, 
...J and underscore, . 

1. Vertical stroke means "exclusive or." For example, A|E means that 
either the character A or the character B, but not both, may be 
written. Alternatives are also indicated by operands being aligned 
vertically, as shown in the next paragraph. 

2- Braces denote grouping. They are used most often to group alterna- 
tive operands or alternative operand forms. For instance, the fol- 
lowing two operand descriptions are equivalent: 

{INPUT I OUTPUT} 

(INPUT 1 
1^ OUTPUT J 

3. Brackets denote options. Information enclosed in brackets may ei- 
ther be omitted or written in the macro instruction, depending on 
the service to be performed- In the following case, the operand of 
the EXAMPLE macro instruction is optional and need not be supplied. 
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I Name | Operation [Operandi I 

I + -»- 1 

|[£yEboi]|EXA:!PLE |[mode] | 



k. An ellipsis denotes that the preceiina syntactical unit can be 

repeated one or more times in sticcession. If the syntactical unit 
consists of one teria^ it is followed by a comiiia ani an ellipsis; 
for example, 

deb address , . . . 

ir-'-^icates that the ter3 ^Ich a-l-iress can be reoeated, with a con^a 
separating each tt^rm froia the succeeding term, but with no coma^a 
after the last teria . 

I If the syntactical unit to be repeate-^, consists of more tnan one 

I term, it is enclosed in braces to indicate the terms that aay be 

I repeated, and the comma and elit»sis are placed outside the braces; 

\ for exasiple: 

{deb address ,optiop] ,.. . 

indicates that '^.ch address, option can be repeated with coFicas 
I separatina each term. !!lo coffima is place! after the last tern. 

5. Uopercase (capital) letters indicate the oortion of the operand 
that must be written e:^actly as shown. 

I)ISP='l£i 

6. Lowercase letters indicate the portion of the operand that is to be 
replaced by a permissible value- The macro description will sneci- 
fy tae permissible values- For exa^iole: 

spacing 

Specified as : 1 or 2 

length 

Spe c ified as : K relocatable expression, or register nota- 
tion (2 through 12) . 

In the first example, either 1 or 2 may be coded as the complete 
operand. In the second operand, ■length • could be replaced by 
HSGLEN {a relocatable expression) , or by (3) as the complete 
operand. 

7. CoEinas and parentheses must be written as shown in an operand 
field. They are delimiters, not notational syikbols. 

M acro D es cripti ons 

The macro descriptions specify the form in which each operand may be 
written . 

For the macro instruction descriptions in this publication, each 
positional operand is specified by a meaningful name or phrase, as 
illustrated: 
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r" — ■ ^ — ^ r~ 1 

I !l a m a | Op e r a ti o n | Oper a n a 

!_ -!__: 1_ 

f[ symbol jnXAF^LE fdcb address 



Each keyword operani is " specifie^l by the k-'^ywor-i, an eoual siqn, ani a 

Meaningiul name or phrase, as illustrated: 



I 1 1 ^ 

IKaae | Operation f Ooerand 



|[ syrr^bol IfEXAMI'LE | DSN.^,ME = ii.ame of iata set 
I I I 



In describing the manner in which an ooerand roay be specified, the 
following terms may be usel- 

Relocat able Bxoression : A relocatable exDression reoresents the nane 
assigned to a field that j»ay be relocated within virtual storaae during 
program execution- (In contrast, an absolute expression represents a 
field tiiat eay not be so relocated.) Ihe value of a relocatable expres- 
sion changes by n if the pro^rask in which it appears is relocated n 
bytes from its oriqinally assigned storaae area. All relocatable ex- 
pressions riiist have positive val'aes. A relocatable expression rcay be a 
sinole relocatable tens. Also, a relocatable expression may contain 
multiple relocatable terms, or a combination of relocatable terms ¥ith 
absolute terms, under these conditions: 

1. The expression must contain an odd nuitber of relocatable terms. 

2. All relocatable terms except one must be paired; pairing is de- 
scribed later in "Absolute Expression -'• 

3. Ihe unpaired terra laust not be directly preceded by a i^inus sign. 

4. A relocatable term must not enter into a multiply or divide 
operation. 

A relocatable expression raluces to a single relocatable value, vbich 
is the value of the odd relocatable tern ad3usted by the values repre- 
sented by the absolute terif^s or paireid relocatable terms associated with 
it. The relocatability attribute is that of the odd relocatable terw. 
Complex relocatable expressions are oermitted (refer to Assembler 
Language) . 

In the following e-^amples of relocatable expressions, SAK, JOE, and 
FRANK are in the saiie control section and are relocatable; PT is 
absolute- 

SAK 

SAH-JOE + FF.ANR 

JOE-PT*5 

SAM+3 

Note that SAM -JOE is not relocatable, because the difference between 
two relocatable addresses is constant. 

Regi ster Notatio n: This is written as an absolute expression enclosed 
in parentheses. The absolute expression, when evaluated, must be some 
value 2 through 12, indicating the corresponding general purpose regis- 
ter. In these examples of register notation, SAK and JOE are relocat- 
able and have the same relocatability attribute and PAL is absolute: 
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(5) -indicates register 5 

(PAL) 

CPAL+3) 

(SAM-JOE) -invalid 

The absolute expression (SAH-JOE) is invalid because it contains paired 
relocatable terms • See A bsolnte Exp r essio n below . 

When register notation is used for an operand r the indicated register 
must be loaded with the desired value before execution of the macro in- 
struction. Mo register other than those stated as being permissible 
should be specified; the integrity of other registers cannot be relied 
upon. See "Osing Parameter Registers" under B-Type Macro Instructions 
below . 

I MX Add ress: 

I (1)Bay be explicit^ written in the same form as an assembler language 

I operand: 

a Cb,c) 

■ ■ • 

I I i 

I I base register 

I I 

I index reaister 

I 

displacement 

I Examples are: 

2(0,5) 
0(2,4) 

I (2) may be implied (indexed) , written as a symbol, optionally indexed by 
an index register. For exasiple: 

IKI-riAL 
ALPMAY (4) 

Hote that ALPKAY is indexed by register ^, 

Symbol ; This may be a symbolic address (that is, a single relocatable 
term) , such as the symbolic name of an instruction in an assembler lan- 
guage program, or it may be a character string use^. for identification, 
not location (such as the ddname parameter of a DCB macro instruction) . 

In TSS, the alphabetic characters are the letters A-Z, plus f, i, it: 
the alphameric characters are the alphabetic characters plus the diaits 
0-9. 

The symbol is written as a string of as many as eiaht alDhaaeric char- 
acters, the first of which is alphabetic. Fsbedded commas an3 blanks 
I are not permitted. Symbols beginning with the charac^ers CHD anA SYS 
may not be used, since symbols beginning with those characters are 
reserved for system ase. Examples of symbols are: 

DDHAJ1E1 

ROGER 

L00P12 

STAkT 

#1 

number: Unless stated otherwise, this will iinDly a decimal integer. 
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Absolu t e Expression ; Tkis may be an absolute term or any arithmetic 
combination of absoliite terms. In absolute term may be an absolute sym- 
bol or any self -defining term. All arithmetic operations are permitted 
between absolute terms- hn absolute expression may contain relocatable 
terms alone or in combination with absolute terms, provided that these 
conditions are met: 

1. The expression must contain an even number of relocatable terms. 

2. The relocatable terms must be paired. 

3. Each pair of terms must have the same relocatability attribute; 
that is, they must appear in the same control section of an 

assembly. 

4. Each pair must consist of terms with opposite signs. The oaired 
teras do not need to be adjacent; for example, PT+IT-ST, where IT 
and ST are relocatable with the same relocatability attribute and 
AT is absolute. 

5. A relocatable term must not enter into a multiply or divide 
operation . 

Pairing of relocatable terms (with opposite signs and the same relo- 
catability attribute) cancels the effect of relocation. The value rep- 
resented by the paired terms remains constant, regardless of program re- 
location. It should be noted that absolute expressions composed of 
paired relocatable terms should not be used as macro operands since the 
attempt by a macro definition to use them in an AIF, SETA and SETB will 
result in an error. The assembler does not assign location counter 
values to relocatable terms until all macro expansions are completed. 

Example: In the absolute expression A-Y+X, the term A is absolute, 
and the terms X and Y are relocatable with the same relocatability 
attribute. If A equals 50, Y equals 25, and X equals 10, the value of 
the expression becomes 35. If X and Y are relocated by a factor of 100, 
their values become 125 and 110- However, the expression still evalu- 
ates as 35 (50-125+110=35) . 

An absolute expression reduces to a single absolute value. 

In these examples of absolute expressions, JOE and SAM are relocat- 
able and defined in the same control section; 3ERNY and DAVE are 
absolute: 

331 

DAVE 

BEBNY+DAVS-SS 
J0E-5A?! 
I>A¥E*4 + BER^Y 

Data Set KaB e: This is the T.ame of one data set or a group of data 
sets. The rules for writina data set names are presented below; the 
types o± names that may be written for each macro instruction are iden- 
tified under the descriptioi! of each macro instruction. 

F ully qualified name uniauely identifies one data set. 

1. A stand-alone data set name identifies a data set that is not a 

member of a oartitioned data set nor a generation of a aeneration 
aata group. The name of a stand-alone data set is written as a 
series of symbols separated by periods. For example: 

DUTASET.TBIAL.TESTI 
TEEI . POGEF . LAURIE 
A.B.C 

50 
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the rightmost synibol is the data set's simple name (TESTI, 
LAUFIEr and C above) ; the other syebols are aualifiers. In TSS^ 
for cataloainq purposes^ the maximuii number of characters in a 
data set namer including oeriods, is 35. The maximum number of 
one-character qualifiers for a one-character name is 17. 

Mote: Data set names created under the IBM OS, or OS/¥S System 
can contain a maximuK of 44 characters; if data sets with napes 
greater than 35 characters are to be cataloqed in TSS, the user 
should employ the ranaiiing facility of the CAT macro instruction 
or CATALOG command to define a suitable TSS name. 

2. Partitioned Data Se t and Fewber ^fame identifies a data set that 
combines individual data sets, called meaibers, into a sinale data 
set. The partitioned^ organization allows the user to refer to 
either the entire data set or to an individual member of the data 
set. 

• The rules for writing the name of a partitioned data set are 
the same as for writina the "naie of a stand-alone data set. 
The parentheses and member name are merely considered as an 
appendage to that name. 

• The rules for writina a member name vary with each macro in- 
struction that can manipulate members. Sometimes (as in LOAD 
and DSLFT:^) only the simple member name (a syebol) is written. 
The full name is not required because the user has indirectly 
defined the partitioned data set (library) in which the module 
resides by assuring that the library is on the program library 
list prior to issuincr those commands. The user could write 

LOAD SORTP. 

if he has previously entered SORTS in a library currently on 
the program library list. 

In other macro instructions (for example, COPYDS) , the user 
must give the fully Qualified member naae. This consists of 
the name of the oartitioned data set suffixed by the simple 
member name in parentheses. For examplfe: 

HQW (OMETRY) 
Q.H.AB(H) 

Here HO* and G.H.AB are partitioned data sets with meirbers 
OMETRY and H, respectively. 

3. G eneration Hames identify data sets which are part of a genera- 
tion data group. These data sets can be referred to on an abso- 
lute or relative basis: 

a- Absolute Generation James are written as the name of the 

generation data group followed by a period and the characters 
GxxxxVyy, where xxxx is a four-digit decimal generation num- 
ber^ and yy is a two-digit decimal version number. For 
example: 

HURST .LI!IER .TT .G0001?00 

HJ.LA4.WW.G0003?01 

HAHQ.G0147V03 

The characters GxxxxVyy are considered a fixed part of the 
overall name. The name of the generation data group (for ex- 
ample, HORST. LINER. TT) is a partially Qualified name applica- 
ble to all generations in the group. 
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If tLe qeneration ±e a partitioned data set, a member (for ex- 
aaple, OOE) within t^at data set is referred to as follows: 

i-B.C.Gxxxxiryy (JO^) 

"t>- Relative Generation 'fame s are written as the name of the 
qeneration data group followed by the appropriate relative 
I generation number enclosed in parentheses, such as: 

G.D.G (0) 

The relative generation number of the most recent generation 
is (0) ; the generation just prior to that is (-1) ; the one be- 
fore that is (-2) , etc.; and a new generation to be added is 
(+1) . For example: 

G0ST.UU.L19P (+1) 
G0S'1-UU.L19P (-3) 

PRQ.T.L5.SfcIF (0) 

If the generation is a partitioned data set, a member within 
that data set is referred to as follows: 

SEKT (-3) (JOS) 

where JOE is the iLember in question. 

f Partially Qu a lified lame s refer to all data sets having a given par- 
f tially qualified name as their common higher-order Qualifier. 

T - Generation Data Group ^am e is the name that is common to each 
generation in the group- Generation data group names are re- 
stricted to a maximum of 26 characters including periods. 

I 2. Otiier Pa r tia lly Qualified Kaiies can also be used to refer to two 
or more data sets. For example, the partially Qualified name 
GO.J1BI4 can be used to refer to both of the following data sets: 
i^O-ABm.A and GO.AB14.B. If these were the only two of a user's 
data sets with the same higher-order gualifier, G0.AB14, and he 
wished to erase thea both, he could do so merely by specifying 
G0.A314 in the ERASE macro instruction. 

Alphameric Characters : An alphameric-character operand is written as a 
string of alphameric characters, the first of which need not be alpha- 
betic. For example: 

lOEODtl 

The limit on the number of characters is given in the description of 
eacn aacro instruction in which it is used. 

TYPES OF MACRO INSTRUCTIOHS 

Most system macro instructions are either F-type (register) or S-type 
(storage) . In this publication, the letter (R) or (S) follows the name 
of each macro instruction description to identify its type; macro in- 
structions that are neither E- nor S-type, referred to as ••other" type 
macro instructions, are identified by (O) . 

Some macro instructions generate literals in their eigpansions. Conse- 
quently, the rules for literal pool coverage must be followed. Refer to 
Assembler language . Section 2, ••Terms and Expressions." Parameters can 
I be contained in the two parameter registers, and 1. 
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An R-type macro instruction does not generate a parameter list; the 
parameters are placed in the parameter registers by instructions in the 
macro expansions- Execution time can be saved if the user places the 
data in the oarameter registers before executing an R-type macro in- 
struction, and uses register notation to specify the operands in the 
macro instruction. 

Address operands in R-type macro instructions are always specified as 
an RX address r or in register notation. This arrangement: allows the 
user to employ indexing, although the addresses passed in B-type macro 
instructions must be oroperly covered; that is, the base register used 
for the passed address must contain the prooer value to ensure that the 
address refers to the desired location in virtual storage- For example, 
assume an E-tyoe macro instruction, RTIPE, which will contain an address 
"area" in register 1 and the "length" of that area in register 0. Its 
external macro description would be: 

I 1 1 — ^ ^ ^ — ^ 1 

f!«ame ( Operation | Operand I 

I 1_ , 1 

|[symbol] lETYPE |area,lenath I 
I 1 1 I 

area 

specifies an address. 

Specified a s: Pegister notation (1 through 12) , in which case the 
address must be placed in the register before execution of the 
iiacro instruction; an FX address 

length 

specifies a length. 

Sp ecifie d as: Register notation (0 or 2 through 12), in which case 
the length must be placed in the reaister before execution of the 
macro instruction; or an absolute expression. 

Us ing Par ameter Reg isters: The user's problem proara.m might be written 
so that one or both of the Parameters are already in the proper parame- 
ter register when the macro instruction is issued. In this care, (1) or 
(0) is written as the operand. Registers 1 and cannot be ased in a. 
macro instruction unless their use is Mentioned in the "Specified as" 
paragraph for the operand. 

S-Type Kacro Instructions 

An S-type (storacre) macro instruction ±e used when the nu!^b'-?r of 
parameters to be passed to the called routine cannot Be contained in the 

two parvaaeter registers. These paraF.eters are place^^ in a parameter 
list whose address is passei to the callei routine in reaister 1- 

There are three forms ot the S-tyoe macro instruction: 

1. The standard form (in which the [11= operand is lefaulte.i) 

2. The I-iorn (parameter list only - specified as fF=I) 

3. The E-torm (executable code only - specified as MF=E) 

S-TYPB, STAiDAh ii FOP F: This for a of macro instruction generates both 
the paraiLeter list reauired by the calleJ. routine and the link aae to 
that routine. If the S-tyoe macro instruction is code3 in a iRodule that 
has a PS'^-CT, the parameter list is generated ir the PSECT. Ifi this 
case, the PSECT must be proi>erly covered bv a base reaister- If an S- 
type macro instruction is coded in a PS£CT, or if it is coded ir. the 

Part 2: nacro Instructions 3 3 



CSECT of a module that has no PSECfv the parameter list is generated 
in-line and coding is generated to branch around it, 

Address operands in S-type standard form macro instructions are 
always specified as register notation or a relocatable expression. 
Hence, they may not be indexed, and the user's problem program does not 
need to provide cover registers. As an example, assume an S-type macro 
instruction, STYPE, that expects the addresses of two storage areas, 
"input »» and ••output," and the "length" of those areas. Its external 
ffiacro description might be: 

J 1 ^ 1 ^ 

I Naae | Operation | Operand | 

I 1 4-_ _, 1 

|[ symbolllSTYlE f input , output , length | 

I 1 1 1 1 

input 

specifies the input area. 

S'pe cit ied as: Register notatior. or a relocatable expression. 

output 

specifies the output area. 

Spe cified as : Reaister notation or a relocatable expression. 

length 

specifies the length in bytes of the input and output areas. 

Specified as : Fegister notation or an absolute expression. 

S-TY PE, L -F01? M: i'his form of lacro instruction creates a parameter 
lisr. 2-forE laacro instructions then link to the service routine and 
point to the parameter list that is generated by the L-form macro in- 
struction- The assembler recognizes an L-form macro instruction by the 
keyword operand MF=L in its operand fieli- 

Eecause the L-forik macro instruction oenerates only a parameter list, 
operand forms that reguire execu-^able code, such as register notation, 
are pro.iibited- The external description of the L-forra S-type macro in- 
struction becomes (compare with the standard form) : 

J , ^ ^ 1 

|23aaie lOperation | Operand I 

I- 1— 1— : ^ f 

fsyiLLol f SLTYPE J[ input, ][ output, ][lenath, ]MF=L | 
I I I I 

input 

specifies the aldr-?ss of the input area. 

Specified as: 1 relocatable expression. 

output 

specifies the aldress of the output area. 

Sp&c ifi ed as: A reloc3.table expression. - 

length 

specifies the length in bytes of the input and output areas. 

Specified as: An absolute expression. 
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The naite field is required in the L-form because it -astiallY becones 
the label of the generated Darameter list and is referred to by tha 
E-f oriii . 

All ODeranis of aB L-form ir.acro instruction (except Mf=L) are option- 
al. Operands that are omitted in the L-form are assuaed to be caDolied 
in the E-forra oacro instruction - 

The L-form aacro instruction generate^:: tne oarameter list at the 
place the eacro instruction is encountered . Because the L-fonn exoan- 
sions contain no executable instructions, they shouli be plac^^i in the 
program so that they do not, receive control; for example, amona the DS 
an i DC xnstructions . hn L-fori macro instruction should never be writ- 
ten in a read-only control section. 

S-TYPE, E -FOk M: A parameter list created by an L-form macro irstruc- 
tion, or by any other means, may be referred to by an £-forn macro in- 
struction. The user can up late a parameter list by supolying operands 
in the i:--torm macro instruction. The assembler recoqnizes an F-fora 

macro instruction by the oresence of the keyword operand in its ooeran--''. 

field: 

MP=CE,list) 

ttere, list should specify the location of the parameter list to be used 
by tae E-form macro instruction. If register notation is specified, the 
register saould be loaded (before execution of the macro instruction) 
with the address of the L-form paraaieter list. The symbol in the naipe 
field of an L-form macro instruction becomes the name of the ^araseter 
list. 

The E-form allows the user to index addresses; however, proper cover 
registers must be provided. The external description of the F-fora S- 
type aacro instruction becomes (compare with the standard and L-iorms) : 



J J 1 , , ^ 

IName | Operation f Operand 

I , 1 ^ 

|[symbol]|SETiPE |[ input, }[ output, ][ length, ]MF= CE,list) 

I I I 



input 

specifies the input area. 

Specified a s: Register notation (2 through 11); an Rl address 

output 

specifies the output area. 

Spe cif i ed a s; Pegister notation (2 through 12) ; an EI address 

length 

specifies the length in bytes of the input and output areas. 

gpec ified as: Register notation (2 throuah 12) ; or an absolute 
expression . 

Each operand except the last is optional. The position of positional 
operands supplied in the E-form macro instruction causes the aeneration 
of values that replace the corresponding parameters in the parameter 
list of the L-form macro instruction . 
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Other Eacro Ins t ructions (Q-Ty^Q> 

2Le system macro iDFtructions that cannot be ciassifiecl as either 
H-tyoe or 3-tyoe are referred to as "other", and identified by (O) in 
the nacro instruction descriotions . For exainole, the SAVE aacro in- 
structioL does not produce oaraseters that oass to a called proaram . 
Its expansion results in instructions in the user*s Broqram that com- 
Dlerely perform x.he re^uestea service. 

f COIIDITIO'fAL ASSErBLY OF FACRO I''^STPUCTIO"^S 

Some Macro instructions can be assembled with non -privileged code 
onlv, some vith privileaed code only, and some can be assembled with ei- 
ther kind of code. However, the DCLISS macro instruction, may be used to 
assemble Macro instructions as desired- For instance, a nonorivileaed 
l]-authoritv proaraitmer can asseiiible privileged code by first issuina a 
DCLISS ■':*B IVILEGSD macro instruction and followinq the privileaed code 
with a DCLk3S USER macro instruction (if sobsequent macro instructions 
that can only be assembled in privileaed code are to be assembled 
correctly, the DCLl^-SS OSEP itacro instruction is issued after the last of 
these) . 

Although a privileged macro instruction nay be assembled in a orivi- 
leged or nonprivileged control section by first issuing a DCLASS PPIVI- 
LFGFD macro instruction, the code thus assembled can only be executed in 
a privileged module- Those macro instructions that are restricted to 
one kind of code or the other return error messages when an attempt is 
m,ade t:o assemble with the inaoorooriate DCIASS settino. The descrip- 
tions of each aacro instruction in Section 2 include cautions (as aopro- 
priate) about the need to issue DCLASS macro instructions, and also 
f about the need to provide save areas, as discussed in Appendix F- A 
summary of those macro instructions requiring the use of ai>propriate 
DCIASS macro instructions is given in Appendix M, together with a fur- 
ther discussion of this topic. 

I HACRO IM31RUCTIO!3 GENERAllOF OF LIIFIALS 

I The TSS assembler olaces literals in a module's first declared PSFCT, 

I if one has been declared- If no PSFCT has been declared, address 

I literals are treated as any other literals: i.e., placed in whatever 

f literal pool is proper. 

I Ii a literal is generated, the user must be sure that the location 

I containing the literal is covered by a base register at the time the 
f macro instruction is executed - 
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SB CTIOH 2; M &CBO INSTR OCf lON BESCBIPTIOHS 

I Figure 2 shows how the macro instructions in this section are de- 
I scribed. Ihe complete descriotions for all user macros are given alpha- 
I betically in this section, except for the TAMII macros which appear in 
[ Appendix N. 

Macro instructions intenied for a special class of users are descriD- 
f ed in System Prograaaer's Guide , Hanaqrer's and Adminis t rator's Guid e, 
I and Multitemin a l T a sk Programning and Op e ration , 



A BEND — Abnormal Task End CS) 

Ihe ABEND macro insrruction serves as an error exit for an assembled 
program, either to terminate execution of the program or to eliminate 
the user's current task from the system, and then return control to the 
user in coaniand mode. 

Standard and E-form: 



I Name | Operation | Operand 



f[ symbol ] I ABEND fexit type, faddress of laessagel "message •} , 

f f f {message id address pmessage id»] 

I I I {r , (parameter address, .-.) ]| ■parameter •} 

I f f[;MF=(E,list) ] 

I i ^ I 



I-f orm: 



flame | Operation | Operand 
[ \ h " 



Isyiibol [ABEND [[exit tyDel,[ (address of oemessage | "message' }, ] 

I I |[ {message id address! ■message id*} ] 

f I |[ { (parameter address, ...) I •^ciraroeter"} ,»^r = I ] 



i_ 



Note : Ihe name field is recruired with ?^r=L. Any reouired operand that 
is omitted from the l-foxm aust be supplied in the E-foria. The operands 
specified in the E-torm will overlay those specified in the L-form. If 

the MP operand is omitted, the standard fore* is assumed. 

exit type 

specifies the return tyoe ox completion code. 

Specified as: (0), 1, 2, 3, or 4. Eyit type 1 causes return ei- 
ther to the conversational user at his terminal or, Ik noncon versa - 
tional mode, to a data ser with the lata definition name ""S^ABEaD, 
to retrieve comicanJs tor execution- In either case, the task is 
returned to command mode. Exit tyoe 2 terminates the user's task. 
If the task is conversational, a new task is created for the user 
and turned over to him as though he had just loaced on. Fiit type 
5 is similar to exit '*-ype 2 in that it terminates the user's task, 
but it does not create a new task or return control to the user. 
The user's terminal is deactivated. Exit type ^4 , in privileaed 
programs only, is similar to exit type 2, except that it is not 
possible to send a message to the user, since the terrainal is being 
held, and the transmission line is physically disconnected and 
disabled - 

If (0) is specified, the exit type sust be loade'! into register 
before execution of this aacro instruction. 

address of message 

specifies the location containing the message to be issue "^ (see 

below) . T'he address points to a one-byte length field that Pre- 
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cedes a field coEtaining the messaae text (the length is in hexade- 
cimal bytes, not to exceed 257) . 

Sp ecified as; In the standard and L-form, a relocatable expres- 
sion; in the standard and E-f orm , in register notation (1 through 
I 12) or an RX address. 

message 

specifies the message text to be issued to SYSOUT when the IBE!ID 

macro instruction is executed. If this operand is specified, 

neither of the last two operands can be specified. 

Specified a s: The text of the message, written as a character str- 
ing enclosed in apostrophes (embedded blanks and special characters 
are permitted) . 

message id address 

specifies the identification of the message to be issued to SfSOUf. 
The identification is an 3-byte code that identifies a message in 
the system (in SYSILF) . If this oDerand is specified, the message 
operanvi cannot be specified. The address must point to an 8-byte 
field containinq the identification, left-aligned and oadced with 
blanks. 

Specified as: In the standard and L-form, a relocatable expres- 
sion; in the standard and E-form, in register notation (2 through 

I 12) or an RX address. 

message id 

specifies the i^ientif ication of the message to be issued to SYSOOT. 

Sp_ecif ied^^ as : "Zhe text of the message identification, enclosed in 

apostroDhes . 

parameter address 

specifies the location of a parameter (see below) that podifies the 
message being displaye^^. This operan-^,. is only used if the message 
identiiicatioB is specified. See the :lote below. 

' Specified as : In the standard and L-form, a relocatable exores- 
sion; in the standard and ?-form, in register notation (2 throuah 
I 12) , or an PX address. 

paraiieter 

specifies information that is to be used to coEBlete or alter the 
iiiessai^e being displayed at the terninal. This ooerand is only 
specified it the messaae identification is specified- 

Sx>e cii ied as: % character strinp enclosed in aoostrophes. 

Mote: The number of parameters or oarameter addresses can be inter- 
mxngled but cannot exceed 23. 

Initialization : If this macro instruction is to be executed in a orivi- 
lege-i module, the F.ost recently issyed DCLRSS aacro instruction in the 
assembly mus^ have specified "^RIVILrOFb (see Appendix M) . Also, the 
address oi a save area i^iist be olaced in register 13 before this macro 

instructxon xs executed - 

ProarammiRq iotes: ABE^^ID with exit ty^e 1 returns the task to command 
mode and removes any previously invoked user control of attention 

interruptions . 

toilowinM an abnormal termination, the vpsW and the aeneral registers 
f are displayed on SYSOOT, toqether with the message text specified in the 
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I ABEMD operand. If different messages are specified for different exit^r 
the error exit taken can easily be identified. 

I'he I'SKABEND data set - miglit contain a sequence of PCS co-^aartc's that 
obtains a selective duikp of the proaram before terminatina the task with 
a LOGOFF command. 

If an error occurs daring the proce*ssing of an exit type 1 condition ^ 
the IBEND procedure is reinvoked, and the error is processed as an exit 
type 2 condition - 

ExaEPles : The user wishes to provide an error exit if his prooraa 
encounters trouble on one path. He includes in that path the b.bE'ID 
macro instruction: 

ERfiOR KBcs^D 1,«I1BS:ID BSC^IDSE TROUBLt^ I^ ^ATH N« 

Ihe user wants to provide messages for dirferent error conditions. 
For his first error coniition, he provides the messaae: 

EEE1 DC AL1(L«TFXT1) 

TEXTl DC C'ABEND FOB INCOMPLETE PATH" 

In the coding path that discovers this first error condition, he 
includes : 

LA l^ERRI 
B EREX 
ESEX ABEMD 1,(1) C0?1M0N EREOIi EXIT 



ADCOM -- Gene rat e a n Ad c on Grou^ [0]_ 

The ADC01 macro instruction generates a grcuo of address constants - 
an adcon group - (see the Programming Notes) for use by a CALL^ LO^. D^ oi 
DELETE ffiacro instruction . 



I ^ — I — ^ r ^ ^ _ — »_ ^ — — — _ — — 

I Name (Operation | Operand 

I— +-- f — 

Isymbol f ADCON Itypa of adcon group [,EP=entry Doint] 
f I |[ ,LErRR= [CODE f ERR} 1 [ , I>ELO?T= [SFO | SDI^} ] 
I I |[ rHSKTAB={XPOS|HOFM] ] 
I I I 



Note: A symbol is reouired in the name field. 

type of adcon group 

specifies the type of adcon group to be generated. 

Specified,, as: One of the following codes. 

Code feaninq 

CALL An explicit adcon group is generated for use by nhe CALL 
macro instruction. 

LOAD An explicit adcon group is generated for use by the LOSD 
macro instruction. 

DELETE An adcon group is generated for use by the DELETE macro 
instruction. 

IMPLICIT An implicit adcon qroup is generated using the externally 
defined symbol specified in the EP operand. 
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I^lTrRJAL An implicit adcon qroiip is aenerated using the i nternally 
defined symbol s"oecifiei in the EP operand, 

specifies the entry point of the i^odule to which the adcon group 
refers. i'or an INTERi^AL a3con aroai>, the R-value indicates the 
oriain of the control section containing the ADCOil macro instruc- 
tion. kiL ADCON macro instruction that specifies INTEBNjIL as the 
type !i.ast consecueT^tly not be written in an unnamed control sec- 
tion. Refer to the ABr and ADCOMD macro instruction descriotions . 

Sp ecxfi ed as: A symbol (one to^ eight aldhanieric characters^ the 
first: of which is alphabetic) - 

Defa ult : If EP is oiittei, eiqht blank characters are used as the 
entry point name for C^.LL, LO^.D, and DELJE'^E adcon groups, whereas 
zero IS used as the emxy point address and R-value for IMPLICIT 
and IMTFR^IAL adcon groups- 
specifies whether the -iynaaic loader is to take an error exit or to 
present a return code if the specified module cannot be loaded. 
The LDEEF operand !!^ay be used only if the -type of adcon aroup is 
LOAD or CALL- 

Specified as : CODE or ERR. If CODF is specified, ADCO^ sets bit 
IDCC2C37 of the ADCC2C control byte to 1 r the dynamic loa.^'er will 
tnen store a return code of X»07» in the ADCC2C control byte if an 
error is encountered while attempting to load the module. If EPF 
is specified or if the LDFRR operanl is omitted, ADCON sets bit 
ADCC^C37 to 0; the dynamic loader will initiate "load error proce- 
dure" when the specified module cannot be loaded. 

Default : ERE 

DELOPT= 

specifies the DTLETE option desired. The DELOPT operand Eay be 
used only with a type operand that specifies DELETE. 

Specified as; SMO or SDK. If SMO is specified, ADCON sets bit 
ADCC3DB7 of the IDCC3D control byte to 1; the dynamic loader will 
then attempt to delete only the specified module. If SDK is speci- 
fied or if the DELOPT operand is omitted, ADCON sets bit ADCC3DB7 
to 0; tne dynaaiic loader will then attempt to delete all modules on 
which the specified module depends, as well as the specified module 
itself. 

D etaul t: SDM 

HSHTAB= 

specifies whether the system or user search chains are to be used 
to locate external names. 

Specified a s: IPOS or ^ORI!^. Mormally (^ORF) , the system search 
chain is used when ADCO^I is issued in a privileged program and the 
user chain is used when ADCO:i is issued in a nonprivileged program. 
The opposite chain is used if XPOS is specified. 

Default: NORM 

Cautions : Although the BP operand may be omitted from the ADCO^ macro 
instrucxioE, the entry point must eventually be supplied to the appro- 
priate fields of the adcon group before the adcon grotip is actually 
used. ADCOH cannot be specified within the first twelve bytes of a con- 
trol section. 

^0 



PageofGC28-2004-6 
Revised 9 May 1979 
By TNL GN20-3941 

Programming Ho tes: An explicit adcon group is altere3 the first time a 
CILL or LOAD macro instruction refers to it. In this altered state, the 
adcon group is said to be disarmed; before being altered, it is said to 
be armed. The ADCON macro instruction may be used to generate a fully 
armed explicit adcon group naving all control bytes and the entry point 
name generated with the desired values. The user may, however, want to 
complete arming by supplying the entry Doint name or control byte set- 
tings after the adcon group is generated- In any case, an explicit 
adcon group must be fully armed the first time it is used by a LOAD or 
load type-E CALL macro instruction. 

Once an adcon group has been disarmed during loading or calling of a 
program, it may subseguently be used in that state only for one purpose 
and under certain conditions. If the program that was loaded or called 
has not been deleted, and if the adcon group used in its loading or 
calling has not been modified either by the ARM macro instruction or by 
the user's own code, the sarae adcon group nay be used in subsequent 
calls to the same program. A disarmed adcon group may be made available 
for the followina purposes only if it is rearmed by means of the ARFI 
macro instruction: 

• Calling or loading the same program again after it has been deleted. 

• Calling the same program again after the adcon group referred to has 
been rearmed for a different prooraa. 

• Calling or loading a different program. 

Mote that an explicit adcon group generated for use by the LOAD macro 
instruc^ion must not be used by the CALL macro instruction and vice 
versa, except in the following situatior . An explicit adcon grouo that 
is used to load a program may be used in subsecuent calls to the loaded* 
program, if the explicit adcon group is not subsequently modified either 
by AHM or by the user's own code, and if the loaded Brogram is not sub- 
seauently deleted. 

If the user issues ADCOl macro instructions, the V-con ard ^~con oair 
are located at a displacement of 12 from the label used for the ADC011 
macro instruction. 

I'he user may refer directly to certain fields of adcon groups of any 
type- These fields are described below; no other f iei Is can ever be 
altered directly by the user. The name for each field or bit oosition 
is the naffie provided by the ADCOMD aacro instruction. All references to 
adcon group fields and bit positions must use these names. 

2IPLICIT ^^DCO N GPOOPS FOP U SE W ITH LOAD OR CILL FACPO IHSTRUC^ IOIS : 

Field .^ame 
For LOAD For CA LL leaning 

ADCC1L ADCC1C Control byte 1 

ADCC1LB7 ADCC1CB7 Bit of control byte 1; specifies the tv^e O'*' ^. 

explicit adcon grouo; bit is for LOAL; 1 for 
CALL a icon groups 

ADCC2L ADCC2C Control bvte 2 

ADCC2L57 ADCC2CB7 Bit of control byte 2: corresponds to the Lr/>:Fr 

operand 

ADCPMAF ADC^NAF Eight-byte field containing as a character con- 
start the naine ox the prograra to be loaded or 
called 

DELSTS ADC ON GROU^ 

Part 2: f^acro Instructions ^1 
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Field tiame yeaning 

ADCC3D Control byte 3 

ADCC3DB7 Bit of control byte 3; corresponds to DELOPT 

operand 

IIDCC4D Control byte ^ in which the iynamic loader 

places the return code indicating results of a 
DELET? request; a return code of X»00« inaicates 
successful deletion; a code X»Otl» indicates no 
deletion took place because the module defining 
the specified SP symbol was not present in the 
user's virtual storage when the request for 
deletion was given; a code X'03' indicates no 
deletior took place because of other outstanding 
references to the specified program 

ADCPNIMD Eight-byte fiel^ containing as a character con- 

stant the name of program to be deleted 

IMPLICIT RDCO!i GROUPS 

Field name feanina 

ADCEP k four-byte adcon, aligned on a fullwor^ bound- 

ary , containing the entry point of the specified 
proara® (V-value) 

ADCRV A four-byte adcon, aligned on a fullword bound- 

ary, containing the P -value of the specified 
program 

C & U T 10 N : because adcon groups raust be caoable of being changed, they 
aiuEt not be generated in read-only control sections - 

Exasiples : 

1. This codinq sequence qenera^es an implicit adcon group for calling 

EXNAFy an externally defined entry point name: 

LA ' 15,LEIKAt 
CALL (15) ,,,E 



LEZHAH ADCOH IMPXICIl ,EP=EXHArt 

This coding sequence generates a DELETE adcon group for deletinq 
only EXHAtI, the specified ^nodule. EX!''AM is assumed to have been 
previously loaded. 



DELETE FFLOC=LEX'^IA« 

LEXKAil ABCOK DELETE, EF=EI^AM,DELOPT=SMO 

ASCQ^^D — Pr ovid e S v sibol ic ":1a m^s for an Explicit Adcon Group (0) 

The ADCOy^ aiacro instrucx^ion generates a dummy control section 
(BSECx) tLat Provides symbolic nanes for the fields in an explicit adcon 

grot:.o. The name of rhe generated DSECT is CHI^ADC. 

42 
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This DSECT permits Fvmbolic access to the resolved v-tyoe and R-tvDe 

address constants that are placed in the explicit adcon grouo uDon 

I execution of a LOAD or explicit CALL macro instroction - The control 

\ byte C2, which directs the loader to a course of action, mav also be 

f accessed. For an explanation of the control byte, refer to the LOAD 

aacro instruction in this section. 

I 1 1 ^ » 

fName f Ooeration f Ooeran^l f 

I ^_- ,- , 

|[sy2bol}f ADCOND \ » 

I I I ^ I 

Mot e : A symbol present in the name field will not be generated. There 
are no operands - 

CAUTION: The ABCOSD macro instruction may be used only once in an 
assen^bly - 

[ Programming Ifot e: The CI control byte is addressable by the followina 
f names: ADCClC (for CALL) or ADCC1L (for LOAD) - The C2 control byre is 
I addressable as ABCC2C (for CALL) or ADCC2L (for LOAD) . The C3 control 
\ byre for DELETE is addressable by the syebolic name ''DCC3D; the C4 con- 
I trol byte for DELETE has the symbolic name ADCCttD. The symbolic '^ame 
ADC¥CO!i addresses the resolved V-type address constant. The symbolic 
name ADCECON addresses the resolved ^-type address constant. When 
ADCC1C is set to X'DO", a LOAD explicit adcon arouD is iEDlied , and when 
set to X»01», an explicit CALL adcon group is implied. 

The macro instruction may aopear at any point in a control section. 
However, if it is written at any location other than at the and of a 
control section, the original control section must be resumed. 

I ExaiLple: The following exairple illustrates how a program accesses a 
I field in an explicit adcon aroup. The proqrain alters the C2 byte so 
that the loader will return codes that indicate the action of the load- 
er. Refer to the description of LOAD macro instruction - 

The ADCON Eacro instruction generates an explicit adcon grotiD for a 
LOAD. ABI! readies the adcon oroup for use by a LOAD. The LA instruc- 
tion places the address of the adcon group into reaister 5. A USIMG 
I statement establishes a base register for CHAADC. The M?I instruction 
I sets the C2 control byte to 1; this setting recuests the loader to re- 
I turn codes when the adcon group is used by a LOAD. 



RALPH ADCON LOAD 



ASM RALPH, SQROUT 

LA 5, RALPH 

USIHG CHAIDC,5 

MVI ADCC2L,X»01» 



SQEOUi- DC CL8«SQR0UT» 
ADCOND 

AETD — Create an Attention Entry ^^able (S ) 

The AETD macro instruction enables the user to byoass the system at- 
tention interruption handler; by pressing the attention key during proc- 
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essmg., he car. enter a oreierinei user-coiei routine to process the in- 
terruDtioii- A number of routines may be Provided to process interruD- 
tion~ ana their entry joints soecifie^ in the operanis of the AKTD macro 
instruction: the desirei rout.irse is then selected by pressing the atten- 
tion key the number o^f times that corresponds to the position of the 
routine in the list of routines specified. 

Standari, I- and E-forms: 

^ — _ 1 J 1 

fil.aiae | Operation | Operand | 

|[ STaibol II a'^TD |[ (Centra- ooint name, save area name],...)] f 

f 'f |[ ,F.F=CLi CE,list)| ] I 

L I I ^ ^ I 

ii2Li-^' "^^^'^ naES field is rec aired with KI=L. If the HF operand is 
o:,iittedr the standard form is assumed. The parameters specified in the 
IJ~lorffi will overlay those specified in the L-f orm . Ihe E-foria say not 
SDecify more ooerands than are sBecified in the corresponding L-form. 

For exa'iiiple: 

SOr ^ETD (El-EYFTi^SAVEA) ,?IF=L 
SEID CSaVEH) ,FF= (E,SUB) 

Wi^en the E-forEi of this !?»acro instruction is executed , the save area 
specified in the L-£orm (SAVEA) will be replaced in thc^ parameter list 
by tae save area specif iee in the E-f orm (SAVE3) . 

entry point name 

specifies the symbolic entry point name of a routine to be entered 
upon pressing the attention key at the terminal. 

Specified a s: A symbol (one to eiaht alphameric characters, the 
first of which must be alphabetic) . 

save area name 

specifies the symbolic name of a 21-word save area that is to be 

associated with the routine whose entry point is specified by the 

first operand. The 21-word save area is provided in addition to 
the standard 19-word save area (which niust be provided in order to 

conform to standard linkage conventions) . The two additional words 
in the 21-word save area are for saving the ¥PSW. 

Specified as: I symbol (one to eight alphameric characters, the 
first of which must be alphabetic) . 

}I ot e : if AETD is issued with neither of the above operands, any 
previously-defined attention entry tables are disconnected and the sys- 
tem resuiies handling the attention interruptions. The systeia attention 
interruption handler can be invoked as an option by including a blank 
entry in the AET (see below). 

I Initializatio n: If this macro instruction is to be executed ±n a privi- 

f leged module, the most recently issued DCLASS macro instruction in the 

I assembly must have specified PRIVILEGED (see Appendix M) . , Also, the 

I address of a save area must be placed in register 13 before this macro 

I instruction is executed. 

Programm ing Hotes : The AETD macro instruction generates a table con- 
taining the addresses of routines that are to be given control when a 
user presses the attention key a specified number of times. Thus, a 
user may specify, by the number of times the attention key is pressed, 
which routine is to be entered. The first time the attention key is 
pressed, the user's program execution is interrupted and procedure 1 in 
the table will be initiated; if he presses the attention key a second 
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time before procedure 1 has been completed , he will enter procedure 2, 
and if he presses the attention Jcey a third time before pro cedure 2 ha s 
been co m pleted , he will enter procedure 3, and so on for as many prede- 
fined procedures as desired. Procedures specified in this manner are 
generally used to communicate with the user's terminal, thus allowina 
program modification at execution time. In order for the user to pro- 
ceed from the first level to the second level, each routine executed by 
the entered level must delay, for example by communicating with the 
user's terminal, because the system does not orovide a delay in level 
processing to allow the user to press the attention key more than once. 
If the delay is not provided by the user's coded routine, then on most 
central processors the user will not be able to press the attention key 
fast enough to proceed beyond level 1 . 

The user might employ the AETD macro instruction to pass control to 
any user-provided control systems, or to provide oartial backup in a 
current task so that an error situation does not have to cause the task 
to be reconstructed froa scratch. It can te used to predefine simple 
automatic debugging procedures by using PCS commands in the AZTD atten- 
tion handling routines. 

ihen the attention key is pressed, registers 0-15 are stored in the 
specified save area. Registers 2-12 are passed to the user routine 
invoked. 

The table that is generated (Attention Entry Table, AET) consists of 
three words containing ¥~type and R-type address constants and the save 
area addresses for each attention handling routine that a user has spec- 
ified. Any null operand pair causes three words containinq binary zeros 
to be created in the table. Entries are generated in the same order as 
given in the operands. 

If AETD is issoed with no operand, the current table (AET), if one 
was previously defined, is disconnected from the system and the systeia 
attention handling routines are invoke',! for subseouent processing of at- 
tention interruptions. 

Iz the A'STD macro instruction is issued with operands, but tae paren- 
theses around the operands are missing, the diagnostic messaae "PAR'P'^- 
THESES E!ICLOSING OPERANDS ARE REQUIRED" will be issued with a severity 
code of 2 - 

Error recovery durina execution of an attention interruption servic- 
ing routine can be accomplisher? by pressing the ATTiJ key a number of 

times corresponding to a blank entry in the AST table (see "Blank i'^T 
Entries" below) - This causes control to be passed to the CoEi-.and Sys- 
tem, which DromDts the user for additional inout . The user can then: 

• Enter commands in an eftort to recover froi* the error, 

• Press the ATTN key to continue with his next seouential AET entry, 
or 

• AETD aay be specified in a user prograir. that is invoked to handle an 
attention interruption in another program, as defined by an AFTI/ in 
that Drograiu, witho^jt causing the first J^ETD to be ignored. See Ap- 
pendix I for a discussion of this facilitv. 

If the save area or entry point is externally defined, it oust be 
used as an argument of an EXxR-l statf^nept in the user's prograTn. if the 
entry point is not externallv defined, it must be usel as the arquicent 
of an EI^TPY stateraent. 

xt-type and E-type aldress constants are noriRally oeneratea for each 
entry point name; in this case, the S-value is the origin of the first 
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declared PSECT in the assembly module containing AETD. If an entry 
point is externally defined, AETD generates a pair of V-type and R-type 
address constants for that entry point operand. An A-type address con- 
stant is also normally generated for each save area address- 

I If a user is usina lETD to handle attentions, the attention handling 

I routine must include a TClilRL TYPE=RESTART (see Appendix N) macro, or 

f the user's default for the implicit operand ATT^fl^ODE must be OLD; if 

I not, then a terminal lockout will occur (see Appendix I). 

Blank AET Entri es - Blank entries may be placed in the AET by skippina 
an AETD operand; that is, by entering three commas (,,,) or by the sys- 
tem when fewer than five AET entries are provided by the user. Thus, if 
a user coles three attention handling routines but codes them as the 
first, second, and fourth operands of the AETD macro instruction, press- 
ing the ATTM key ttiree times will pass control to the command system. 
If he codes them as consecutive operands, pressing the ATTN key four 
times will pass control to the command system. 

Example : In the following examole, the user has provided two attention- 
handling routines having the entry points EPHODA and EPMODB respective- 
ly. If the user presses the attention key at the terminal once follow- 
ing execution of the first AETD macro instruction, control will be 
passed to the user-coded routine at EPJ'.OBA. khen the user presses the 
attention key a second tiiae before the routine at EPWODA has completed 
execution, control will be immediately oassed to the routine at EPMODB. 
Execution of a second AETD macro instruction, having no operand, will 
return control of attention interruptions to the appropriate system 
routines . 



AETD (EPMODA ,SAVA ,EP'€ODB , SAVS) 



AETD 



ABM — Initialize_^ an Ex plic it AJ con Gro uB ( 0) 

The ALii iiacro instructioi? initializes (arcs) an explicit adcon group 
(see the description of the ADCOl macro instruction) , so that it may be 
used by a load type-S CALL aacro instruction or a LOAD macro 

instruction . 

Explicit adcon groups must be initialized if: 

1. They iidve already been used to refer to one program and the saae 

adcon^ groiip is to oe used to refer to a different program. 

2. The adcon arouo has been used at least once and the associated pro- 
graia Las been deleted by the DELETE macro instruction. 

3. 'They were generate! bv an ADCOjI macro instruction without the EP 

operand. 

I 1 ! r 

INa^e, f Ooeration lOperan i I 

|. ^_ j-,-_ , 

I [ symbol ]| aH?^ I adcon arou^ address, external name address | 

lI J 1 I 

a3con^ group address 

specifies the address of adcon grouo to be initialized. 
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Specif iei^ as : ' An RX address, or register notatioB (2 through 12) . 

external naEie address 

specifies the address of aF eiqht-byte field that contains the ex~ 
ternal name that is to be pieced in the exolicit adcon aroiii>: the 
name of the module, entry point, or control section to be loaded or 
called. 

Specified as r Jin RX address, or register notation' {2 throuah 12). 

R eturn Data : After execution of the ABK macro instruction, reoister IS 
contains the address of the aried adcon aroup. 



I AWAIT — Wait for an Interruption (R) 

The AikAiT Eacro instruction enables you to check for the co'iPletion 
of an event and to enter your task into the delay state to awaiit 
completion. 



fKame fOperation ( Operand 
I 1 1. 



I [ symbol ]ritW?iIT \ 

I I L- 



ilQte : There are no ooerands. 

Execution: The AWAIT routine checks whether the SVC (1) was the subject 
of an execute (ILC=2) and (2) is positioned on the second half word of a 
fullword (implying an event control block) . If both of these conditions 
exist, the event control block complete bit (bit 1 of the first byte) is 
checked. If this bit is on (or if any enabled interruptions a"^e pendirui 
on the task's TSI) , the event is complete, no waitina is required, and 
control IS returned to the issuino program. If this bit is off, a wait 
is required; the task is put into the delay state. 

Proqramiitinq note : AkAIT resets ISALCK (if previously set) and allows 
any interruptions enabled in the VPSW. 

Example : Suppose you want to place your task in the delay state (inac- 
tive TSI list) until an 1/0 operation is completed. lou might write: 

WAIT 

ECB 

S^COHB BIT IS COMPLETE BIT 
AWAIT aUST BE SUBJECT OF EXECUTE 

BPKDS — BUILTIM Procedure Keyword Dictionary (O) 

The BPKDS macro instruction, in conjunction with the BOILTI^' facility 
of the command system, provides for specification of prototype coamand 
parameter lists that may include siPiple keywords, self-defining key- 
words, repeating keywords, list keywords and repeating list keywords 
(which may be unnamed) . 

Standard form: 

I Name | Operation | Operand \ 

I 1 ^ ^ . ^ , 

lextname f BPKDS (entry [, parameter ,..-][ ,MF=I ] | 



EX 


0,EC3-»-2 


B 


SOMEPLACE 


DS 


0? 


DC 


H»0» 


AWAIT 
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I L-rorm: 



^ J J ^ 

|;iaE-.e I OD^rat ion f Operand 

I- ^ h- f 

I label IB1KD5 | [ ^parameter , . . - ],HF=I: 

I I i : 

E-tom: 



I J 1 ^ , — . 

I Same | Operation [ Operand 

lextnaiie fBPKDS | entry ,K F= (E , label , count) 



extnaae 

specifies the syiabolic name of the keyword dictionary, to' be used 

as tiie exterrtal naae (SXTWARE) operand o^ the BUILTI!! command.. 

Spe cif iei as: a symbol, one to eiaht alphameric characters, the 
first of which mvtst be alphabetic. 

entry 

speci£i'?s the symbolic name of the starting point of the routine 
tiiat is to execute the co!nF*an.5. 

Specif iei as : a symbol, one to eiaht alphameric characters, the 
first of which must be alphabetic. 

Mote: entry may 'be external to^ the module in which the 3"^KDS 
occurs; if entry is in the sasre module as BPKDS, it need not be an 
ESl-RY point - 

label 

specifies the symbolic name of the L-form BPKDS to be used with the 
E"f ori. - 

Specified as : a symbol, one to eiaht alohameric characters, the 

first of which Eust be alohabetic. 

count 

specifies the number of first-level keywords in the L-form used by 
the E-£oriL. 

Specified as : a decimal integer, 1 to 255 inclusive. 

parameter 

may be: 

keyword simple keyword 

♦keyword self ~def ining keyword 

keyword.. repeating keyword 

{keyword, sub-parameter[ ,--. ]) list keyword 

(keyword .- ,sub-parameter[ ,... 1) repeating list keyword 

(.., sub-par ameter[ ,... 1) unnamed repeating list 

Mote: in the above expressions, sab-oarameter may take anv of the 
forms allowed for oarameter; keyword is a symbol to be recognized 
as a keyword in the user's coamanl operand list. 

Spe cified as: one to eight alphameric characters, the first of 
which must be alphabetic. 
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Mote: The I-form and E-form must be in a private read-write coBtrol 
section. The L-form should be in a read-only control section. Any nuia- 
ber of l-forms may reference one L-form- 

A simple keyword is used in the command as "syiDbol=string" and is 
resolved as a parameter list entry which points to the string. 

A self -defining keyword is used as "symbol**, "NOsymbol", or "syiiibol= 
string", and is resolved as a parameter list entry which points to a 
character string. Specification of "symbol" points to a string ^Y* ; 
"HOsymbol" points to string 'N*; and "syiibol=string", eguivalent to a 
simple keyword, points to the string. 

K repeating keyword is used as "keyword=string1 [string2] [,...!" and 
is resolved as a parameter list entry which points to a parameter list- 
The entries of the second list point to the strings. 

A list keyword is used as "key word= (sub -parameter 1 [, sub-parameter? 
[,...])" or as "keyword=string", and is resolved as a parameter list 
entry which points to a second parameter list in which element is one of 
the Eub-parameters . The seconi list points to character strinas and-or 
further parameter lists, as reauired by the BPKDS specification of the 
sub-paraBeters- Using "keyword=string" is equivalent to using 
"keyword= (sub-parameter l=string) " . 

Macro e xpansion : BPKDS I-forin generates a chained keyword dictionary, 
containing no alterable data. The physical structure of the dictionary 
is unpredictable. The logical structure is a relatively simple mao of 
the prototype parameter list. The iictionary may be used to drive spe- 
cialized parameter-retrieval routines, such as retrieval-by-keyworr* . 

The E-form (one is generated by the I-fom) generates the anchor or 
root, of the dictionary and also provides command entry point inforSia- 
tion for Ithe 3UILTIN processor. It contains alterable data. 

The current level of DSECT CEABPK properly describes the entire 
structure. 

Coamand p roc essing: The CZATI' command analysis routine, which is 
invoked to Process a command, provides complete analysis of B?^DS- 
defined coimand parameter lists. The analysis function includes full 
DEPAOLT searchina in addition to construction of chainei, ordered, and 
counted parameter lists mapped by the prototype parameter list. 

A special entry point tO' CZATE aay be called uj privileged programs to 
perform B?KDS-controlle5 analysis of internally generated paraT.eter 
lists. A laacro or direct call entry to a command routine can have the 
same parakieter list capability as a coEmanl call entry by using the sase 
Parameter retrieval code. 

Para riet er an al ysis: Opon entry to the command routine specified by 
BPKDS, general register (1) points to the first level parameter list 
which is normally built in the area provided by the E-form or the macro - 
The entered program must reqar<? the entire parameter structure as being 
read-only. The logical organization of the analyzed Parameter list 
corresponds to the BPFDS prototype list: the physical structure is 
unpredictable . 

Macro cal l proc essing: The following call laakes the full parameter str- 
ing analysis facility available to a coiffi.ani routine callel li^ectlv fcv 
another prograri: 

CALl CZAiE6, (string ,bpkds,optiO'n) 

Fart 2: Macro Instructions U9 
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where: string is the address of the command parameter string to be ana- 
lyzed (iiust be terminated by the character X*2T) ; bpkds is the address 
of the E-form or I-form BPKDS macro to be used; and option is the 
address of a one-byte switch that must contain I*01» if default and 
synonym searching is to be done: otherwise ^ it must contain X'00»- 

Ee turn codes : upon return, the low-order byte of register 15 will con- 
tain one of the following return codes: 

Code M eaning 

)(»00» successful 

X»04» bokds (the address) did not Doint to a valid 3PKDS 

X*06« string was lonaer than 256 bytes 

XMO« option was not X»01» or X»00» 

The parameter tree that would normally be pointed to by reaister 1 
will be found at location BPKSPUR of DSECT CHABP^. 

BSP — Back s pac e a Block [B.]_ 

The BSP macro instruction (for BSIF) backspaces a block on the cur- 
rent magnetic rape or direcr access volurae. Backspacing is always 
toward the load point (or beginninci-of-f ile on direct access) regardless 
of the OPEi macro instruction's Parameters or the direction of reading. 

This macrO' instruction is applicable only to magnetic tape or a ?li- 
rect access device and becomes a MOP to^- other devices. 

I 1 1 1 

IMaiie I Operation I Operand ( 

I- 1— 1— f 

f[ symbol If BS? f deb address f 

I I I 1 

deb address 

specifies the address of tae data control block opened for the data 
set to be backspace!. 

Specified as: An RX address^ or register notation (2 through 12) . 

Init ial ization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCL'.SS macrO' instruction in the 
assembly lust have specified PRIVILEGED (see Appendix M) . Also, the 
act.-'.ress ot a save area must be placed in raqister 13 before this macro 
ins'cruction is executea. 

CRIITIO^ : Abnormal xerEi nation occurs if: 

1. The ddxa control block specif ie:I by the user is not validly opened. 

2. The track overflow option is specified. 

3. kll real ani write operations have not been checked for completion - 

C.^. UT IO:^ : Two BS"^-^ macro instructions should not be issued 'on a -direct- 
access data set without an intervenipcr I/O operation (such as road or 
wrixe) . Ir two consecutive backspace operations are attempted, the 

second oSI-- macro instruction will not cause a backspace. 

Return Data : Following ezecation of the BSP macro instruction, register 
15 contains a return cole of X*30» if rhe operation is completel normal- 
ly. It alr.o contains a return code of I'OO" if the operation encoun- 

xerei a per^ianent positioning error, in which case the next CliSCK of a 
SEID or '^BITE passes control to the 'JY!iaD routine. 

SO 
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If two BSP aacro instructions are issae*1 without at least orie inter- 
vening I/O operation, a ^e^•lrn code of X»0^' is place "^ in reoister IS, 
indicating that the second BSP macro instruction was not execute}. 

It a tape mark is encountered on a backsoace, the tape is reposi- 
tioned to its position before BSP was itsuei; a return code cf X»04" is 
placed in register 15. 

If tne user attempts to backspace into a header or trailer label 
tracli on a direct access volume, lackspacina does not occur and a return 
code of X»04» is placed in register T^- 

P rogramHiinq Motes: All real or write ooetations must be checkec^, for 
completion before the 53? macro instruction is executed. 

Eather than issue more than one BSP without an intervening HFAD or 
WRITi!i, .lOTii, ^OINT, or C*ITBL macro instructions should be used. 

CALL — Call a Modul e (S) 

vhe CALL nacro instruction passes control fron one nodule to another 
module or froit one point in a module to another point within the sasre 
module. 

the ptoaule issuing the Ci\LL macro instruction is ret erred tc as the 
calling Eolule; the module receiving control is referred to as the 
Called module. 

Standard forn: 

I 1 1 » 

|Name fOperation (Operand f 

I 1 4_ 1 

I [ symbol ]| CALL fentry point na»e ,[ (oarameter address,..-) l,f?Ll f 

f f I [ . fl^ 1 1] 1[ ,ID=identif ier ] ' | 

I I 1 ^ 1 
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L-form: 



[Mame I Ooerat ion | Operand 



Isymboi ICALL | ,[ (paramer^r adr'^ress) ,.-.}#[ VL ],HF = L 

I I I > 

}Tote: A FYabol is reouirei in the name field of the L-form. 



S-£orni : 



|"affie f Ooeratior. lOoerand 



|[ syiibol ]|CALL I entry Doini: iname,r (oarameter address,...) ], | 

f I |[VLX r {T-fl} ][ ,ID=i-ientifier],MF=(E,list) ' | 
I 1 1 1 

entry point: name 

specifies the syiLbolic nane of an entry point to which conrrol Is 
to be passe i. 

Spec ifiei as: A symbol (one to eiaht al'^hameric characters,' the 
first of which musx be alphabetic) ; or register notation (15 only) . 
If the module is not reent«^rable , the symbol can be: 

• the name of a control section, 

• the name in the oiperand field of an assembler languaae eNTPY 
stateBient, or 

• a module name. 

If the modiiie is reenterable, control section name must not be 
used. If register 15 If specified, and the load type is I, the 
address of an implicit adcon group mast be loaded into register 15 
before exec^ition of this macro instruction. If reaister 15 is 
specified and the load type is E, the address of an explicit adcon 
group laast be loaded into register 15 before execution of this 
macro instruction (see the Programming !lotes) . 

parai.eter address 

Specifies the address of a parameter to be oassed to the called 
proaram . The paraiEeters must be written as a sublist enclosed in 
parentheses. If one or more parameter address operands are writ- 
ten, a parameter list is generated; it consists of a fullword for 
each operand. Fach fullword is alianel on a fullword boundary and 
contains the address to be oassed. The addresses appear in the 
parameter list in the same order as in the macro instruction. 

khen the called progras. is entered, register 1 contains the address 
of the Darameter list. If the E-form macro instruction is used, 
the parameter addresses overlay the corresponding L-form parameter 
addresses . 

Specified as: In the standard and L-form, as a relocatable expres- 
sion; in the standard and F-form, also in register notation (2 
through 12); in the S-forin^ only, also as an BX address. 
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specifies that the first word precedina the parameter list contains 
a binary number eaual to the number of parameters (including null 
parameters) supplied by tke parameter address operand. 

The operand parameter list is fixed-length if it contains a known 
number of parameters every time the called program is given con- 
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trol. The list is variable length if it contains a varying nuiaber 
of parameters. In the latter case^ the VL operand must be included 
so that the called program will take action to determine the length 
of the parameter list being passed. 

If VL is specified on the S-form, it must have been specified on 
the L-form; if VL is not specified on the E-forM, it must not have 
been soecified on the L-form . 

Specified as: VL 

{Efl} 

specifies whether the call is explicit or implicit. 

Specified as ; 

E - an explicit call is requested - 
I ~ an implicit call is reguestecl. 

Default: I 

1D = 

specifies a binary calling segaence identifier for the CALL macro 
instruction- This parameter may be used to identify the CALL macro 
instruction uniquely. This parameter generates a NOP (see th3 Pro- 
graaaing Notes below) - 

Specified as: An absolute expression, maximum value 4095. 

Programgiinq No tes: The explicit CALL macro instruction causes the named 
Erodule to be loaded (if necessary) during execution; it may then be 
deleted through use of the DELETE macro instruction (refer to the DELETE 
aacro instruction in this section) - If an imolicit CALL macro instruc- 
tion is issued, the called object nodule is already in virtual storage 
and may not be deleted by the callina object module through use of the 
BSLSTE macro instruction. 

An ijuplicit adcon group consists of two contiguous fullwords: the 

V-type and R-type aldrers constants of the entry point. These address 

constants Must be coded as a V-type followed by an H-tyoe. See Examole 
2 below. 

An explicit adcon group ikav be aeneratei through the ADCOH macro in- 
struction. The ARF macro instruction can be use3 to reinitialize the 
adcon group- 

L ADCON CALL,EP=entry point name 

Fefer to tne ABCDJ and ,\EK macro instructions in this section. 

If (15) i£ written for the entry point name operand of an ei^olicit 
CALL macro instruction, the exolicit adcon grouo should be armed if nec- 
essary and then reused for any subseguent calls to the desired progrart!. 
ADCOI;! is capable of generating an armed adcon group (refer to the AHtl 
macro instruction in this section) . P'owever, the exolicit adcon group 
is altered by the execution of the firsc CALL macro instruction and can- 
not be reused if the aiodule has been deleted (refer to the DELETE aiacro 
instruction) . If an object moc^ule has not been loaded or has been 
loaded and then deleted and it is 'desired to call it using a previously 
used explicit adcon group, it is necessary to issue or reissue the AR^ 
macro instruction. The ARF macro instruction adjusts the explicit adcon 
group so that it may be reused. Fefer to Examples 4 and^ 5, the SDCOM 
Eacro instraction, and the h?iK macro instruction. 
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If tihiB entjnf polBt: nane operand ^ecif ies an internal s^fisliol, it: vast; 
appear as tilie c^erand €£ an asseai}ler langnage ENTRl st:atement. ^Elie 
reason for Uiis rule is tliat the called naoie Hast lie in tlie prograa 
nodole dictlonar]f CPM)! if the CJkLZ macro instracticn i^ to execute 
properly, 

l^pon entry to the called program, the IB irali]^ can be detemined liy 
e«iiwining the location whose address ±3 €X»itained in register 14; the 
address is that of a folliiord, the loit-order titc hytes of which ccaitain 
the ID. Hhen CMiL is specified as: 

CMX 1151^ 131 ^^,III=dL6 
the expansion cxmtains the following <xide: 
BASB 1<I,15 I.IIiE 

DC x"ii700* n mm 

DC M.2fl61 ID UTEO aPHUHID FISLD €& WIOB 

Retom Data s Begister 14 cxaitains a iialid retam ^^ress wl^n csontrol 
is passed to the called aiodale. !Eheref ore« by issuing a SJSTOItB macaro 
instra<:ti€m or branching to the address in register 111, control is 
transferred to the instracrtion after the CIM. sacro instraction in the 
calling aiodnle. The CHIIi mmcsco instraction is advantageous because it 
elininates the need for writhing linkage to the <:alled laodule. 

I,- and EHFcnn Use s E-f ooi parameter list entries overlay the corre- 
sponding Ii-form parameter list entries* 

1!his example stews Ir- and 1-form uses 

M.S&Ji €M1m , CH « ,CI ,ill==I. 

ISITA CMJ. R'mA,€,B,l,ID=36,lfI^CB,&I^llk} 

Bxaamles t Ihe following are typical examples of ioqplicit and explicit 
use of CMX« 

snJiPIf 1 - Implicit CMMmZ 

BKl OIUi BUT 

Hhen the C^IX macro instracrtion in the calling program is executed, 

control is passed to HIT* 

MX&ia^IM 2 - Implicit adcon group t€3at mk implicit €:MLLt 
EX2 CMIm €15) , tABC^DBl) ^W. 
Calling pr<igram contains an ioiplicit^ adcon groiqp: 
SMmmm jidcoii iifra.iciT,iF^=ci.DBtp 

Before the CUM. macro instnxrtion is executed, register 15 must be 
loaded with the address of the adcxm grcsup; for exaoqple, lA 15,SMf^MM[. 

Hhen the called program is entered, register 1 points to a two^wcHrd 
parameter list* The first word contains the address of ABC; the second 
word contains ±im address of DBF. The word preceding the parameter list 
contains a 2, indicating that two words cxmtaining the addresses of 

parameters f ollow.« 
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EXAMPLE 3 - Explicit CALL: 



EX3 



CALL ATOL , ( BAT ^ CAT) , ^E 



At execution time^ the program whose entry point name is ATOL is 
loaded into virtual storage (if necessary) and control is transferred to 
ATOL. When the called program is entered, register 1 points to a two- 
word parameter list that contains the addresses of BAT and CAT, Regist- 
er 14 contains the return address. 

EXAMPLE 4 - Repetitive explicit CALLs, reusing an explicit adcon groups 



ARM 
CALL 



MAX , JOE 
(15),,,E 



CALL (15),,,E 



CALL C15),,,E 



MAX ADCON CALL 

JOE DC CLS'CALLEE' 



EXAMPLE 5 - Repetitive explicit CALLs with an intervening DELETE, reus- 
ing an explicit adcon group. 



ARM 
CALL 



MAX , JOE 
C15),,,E 



DELETE EP=CALLEE 



ARM 
CALL 



MAX , JOE 
(15),,,E 



MAX 
JOE 



ADCON 
DC 



CALL 

CL8 • CALLEE ■ 



CAT — Create or Change Catalog Entry CS) 

The CAT macro instruction creates a catalog index for a generation 
data group, or renames a data set. For physical sequential data sets, 
CAT creates or alters a catalog entry. 

The CAT macro instruction can he coded with either of two sets of 
operands, depending on the objective. To rename a VAM cr physical 
sequential data set, to change a version number of a generation data 
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group, or to create or alter a catalog entry for a physical sequential 
data set, use: 

Standard form (see "Operand Strings" in Part II, Section Ds 

I Name | Operation | Operand | 

1 [symbol] |CAT j /address of operand string 1 j 

I I ll'data set name 1,{N| U>, C {R|II>1 l,data set name 23'J | 

L X ^ J ^ -J 

L-forro Csee "Operand Strings" in Part II, Section 1): 

^ ^ . y^.. ^ ^ ^ ^ ^ 

I Name | Operation | Operand | 

I 4 + ^ 1 

Isymbol JCAT j ■<aata set name l,tN|U},E {R|UJ] (,data set name 2]' | 

I I I ,MF=L t 

Note: h symbol is required in the name field. 
1-form: 



[Name j Operation! Operand j 

l.„ ^ 4 . J 

j [symbol 1 1 CAT |MF=(E,list> | 

L X ^J . . . . J 



To create a generation data group for VjyM or physical sequential data 
sets, use: 

Standard form Csee "Operand Strings" in Part II, Section 1): 

J. ^^- ^ -I , ^ ^ ^ ^ ^ . . ^ — -, 

I Name [Operation! Operand | 

I ^+ + —^ .^ ^ 

I [symboll I CAT |\ address of operand string } \ 

I I j t'GDG=gdg name,number,[{A|0>l [,ERAS1={¥|N}3" J | 



L-form Csee "Operand Strings" in Part II, Section 1): 

^ ^ ^ ^ 



I Name [Operation! Operand | 

l.^. „+ ^ ^ 1 

jsyrobol fCAT | ■GDG=gdg naroe,number, [ {A|0>H ,1RASE==CY|N}] ■ ,MF=L | 
Note: A symbol is required in the name field. 

E-form: 

J J. ^ ^ — , ^ ^ . ^ ^ 

I Name | Operation | Operand | 

I [symbol3lCAT lMF=CE,list> | 

address of operand string 

specifies the address of the first operand in the operand string. 

Specified as : Register notation C2 through 12 ) or a relocatable 
expression. Note that the operand string can also be specified as 
a character string enclosed in apostrophes, as shown. 
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<lat:a set name 1 

specifies the name of an imcataloged SAM data set defined in a DD£F 
macro instruction or command, or specifies any cataloged VAM or SMI 
data set name. The name may be that of a VhM data set only if a 
generation index is to be created or the naire cf the data set is to 
be changed* The data set must reside on a direct access or iragnet- 
ic tape volume. 

Specified as ; 

• The fully qualified name of a partitioned or nonpartitioned data 
set or a partitioned or nonpartitioned generation data group Ci- 
dentified by absolute generation name or relative generation 
number). 

• The partially qualified name of any data set other than a genera- 
tion data group. 

mim 

specifies the updating of an existing WlM or SAM catalog entry CU), 
or the creation of a new SAM catalcjg entry IN). 

Specified as ; 
N (SAM only) or U 

CB|U} CN/A for VAM) 

specifies the owner access qualification for SAM data sets; 

Specified as ; 
R - read-only access 
D - unlimited access 

If R is specified, the data set oimer may erase but not write into 
his data set. 

Default ; U 

Ihis default is valid only if a new catalog entry is being made? 

otherwise, no change is made to the access qualification.. 

data set name 2 

specifies the new name for the data set. This operand is r^cessary 
only if the currently defined name of the data set is to be 
changed. The data set name may have a relative generation number 
appended. 

Specified as ; 

• The fully qualified name of a partitioned or nonpartitioned data 
set or a partitioned or nonpartitioned generation data group Ci- 
dentified by absolute generation name or relative generaticn 
number). 

• The partially qualified name of any data set other than a genera- 
tion data group. 

GDG=gdg name 

specifies the name of a new generation data grcup. 

Specified as ; GDG=gdg name, where gdg nsme is a data set nane as 
defined in Part II, Section 1. 

number 

specifies the number of generations to be iraintained in the genera- 
tion data group. 

Specified as ; An absolute expression. 
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specifies the acticn to be taken when the next generation (beyond 
the nijimber specified in the previous operand) is being cataloged in 
the generation data group. 

Specified as ; 
A - all previous generations are to be removed from the catalog, 
O - only the oldest generation is to be removed. 

Default ; O 

ERASE= 

specifies the disposition of old generations deleted from the cata- 
log. This applies to private volumes only; data sets on public 
volumes are always erased when uncataloged. 

Specified as ; 
Y - erase external storage belonging to old generation data group 

members . 
N - save old generation data group members. 

Default s N 

Initialization ; If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVIIEGED (see Appendix M). Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

programming Notes ; The system automatically recatalcgs multivolume data 
sets that expand or contract. 

When data set name 1 is given, a new entry is made in the catalog if 
the N option was specified. When the U option is given, the catalog 
entry is updated with the requested changes to the data set name (VAW 
and SAM data sets) and/cr access qualifier (SAM only). In addition, 
when data set name 2 is supplied, a change is made to the name in the 
data set labels (DSCBs) on the volumes containing the data set. This 
step is omitted if the volumes are on tape. 

If the GDG keyword is specified, an index is created for a new 
generation data group using the parameters supplied. If the generation 
data group is already cataloged, nc updating is possible. 

If the data set name is specified with a member name, only the data 
set name itself is used? the member name is removed. 

If the user wants to change the definition information for a cata- 
loged SAM data set, he may do so merely by issuing a CAT macro instruc- 
tion with "update'* indicated (U). 

For private data sets only, the owner of a generation data group is 
allowed to catalog generations of that group- Sharers, regardless of 
their level of access, are not permitted to do this. 

Generations of a generation data group that reside on private storage 
can be saved by the user even after they are uncataloged. 

Return Data : At completion of execution of the CAT macro instruction, 
the low-order byte in register 15 contains one of the following codes; 
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Code 

(Hexadecimal) Significance 

00 Cataloging accomplished as requested 

04 Name cannot be changed since new data set name not 

unique, no cataloging 

08 Invalid element in input string 

OC No cataloging for other reasons 

10 Data set name not unique, already in catalog 

14 No volume of data set mounted? cannot catalog 

20 VhM data set not GDG or rename option 

24 Open DCB 

Examples ; In EXl, the operands are presented as a character string. In 
EX2, an address designates the location of the operands. 

1X1 CAT •DATASET,U,U' 
EX2 CAT OPLISTC 

CDD — Retrieve and Execute DDEF Commands CS) 

The CDD macro instruction retrieves one or more DDEF commands from a 
line data set containing prestored DDEF commands (line data sets are 
discussed in Command System User's Guide ), The macro instruction pro- 
cesses the retrieved coiranands as though they had just been entered by 
the user. The user can thus create a line data set of cxjramonly used 
DDEF commands for reference through the CDD macro instruction, eliminat- 
ing the need for direct DDEF macro instruction or command entries for 
each run of a program. 

Standard form (see "Operand Strings* in Part II, Section 1): 



J- — ^ ^, ,, ^ ^ . — 

I Name | Operation | Operand 

, + ^ 

I [symbol] I CDD | (address of operand string 

I I ft 'data set name[,DDNAME=data definition name, 

h-form (see "Operand Strings" in Part II, Section 1): 

I Name | Operation} Operand | 

I. + ^»-4 , 

I symbol I CDD | "data set name [ ,DDNAME=name ,...]' ,MF=I, | 

Notes A symbol is required in the name field. 

E-form: 

I name j Operation j Operand | 

|. ^„„+ _^.^4. 1 

I tsymbol]|CDD |MF=CE,list) | 

L ^^X ^ J . . ^ . J 

address of operand string 

specifies the address of the first operand in the operand string 
(see "Operand String" in Part II, Section 1). 

Specified as s Register notation (2 through 12) or a relocatable 
expression. Note that the operand string can also be specified in 
the operand as a character string enclosed in apostrophes, as 
sho%«i- 
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data set name 

specifies the naae of the line data set containing the prestored 
BDEF commands. See "Data Set Name" in Part II, Section 1. 

Specified as : The fully craalified name of a nonpartitioned data 
set, or of a nonpartitioned generation of a generation data group 
(identified by absolute generation name or relative generation 
number) - 

specifies the name of a particular DDEF command in the data set. 

Sp ecifie d as: A symbol (one to eight alphameric characters, the 
first of which must be alphabetic) . 

Def ault : All DDEF commands in the data set are retrieved and 
executed . 

In itia l izati on: If this macro instruction is to be executed in a privi 
leged module, the most recently issued BCLASS macro instruction in the 
assembly must have soecif iei PRIVILEGED (see iDpendix ??) . Ilso, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

CA miQM : The user must make sure that none of the DDEF commands or 
macro instructions for his task has tne same name as a DDEF command re- 
trieved through this macro instruction. 

Return Data : At completion of execution of the CDD macro instruction, 
the low -order byte of register 15 contains one of the following hexade- 
cimal codes: 

Code Significance 

00 Successful completion 

04 Invalid iata set narse 

08 Invalid lata definition name 

OC Data definition name not in data set 

10 Error return from DDE? routine 

14 iot a line lata set 



I CKDEr'HAC — G enerate Error ?!ess age f O) 

Tnis inner macro ins-*- ruction is used to generate error messages per- 
taining to errors encountered in macro expansions. 



iKa^e I Operation f Operan^'! 



[ [ symbojL ]|CHD^B MiiC Inessage number ,[ opera n-^. name], 

I I [outer operand 11, [outer operand 2], 

I I [outer ooerand 3 ][ ,S=severity code] 

I -i I 

message nam per 

specxf ies the message to be generated . 

Specified as : A number. *^ersaqe numbers and the messaaes thev 
identify are shown in lable 1. 

operand nawe (opnm in Table 1) 

specixies the race of an outer sacro instruction operard, or other 
inforiiation define! by the programiiier . 
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Sp ecir ied as : >. character string (a character striEg contains no 

embedded blanks or coi^Las and is not enclosed ii? apostrophes) - 

outer operaiii 1^ 2, and 3 (oova, oP¥b,. and odvc in Table 1) 

specify operands of the outer macro instruction . A maximum of 

three operands can be specified in any one error messaae. These 
OBerands nay also be used for other purposes, which tae orograEmer 
defines. 

Specified as : A character strinq (a character string contains no 
embedded blanks or cosF'as and is not enclosed in apostrophes) . 

S= {sc in Table 1) 

specifies tne severity code associated with the error- 

Specified as : 0, %, or 2. The Eeanincfs of these severity codes 
are as follows : 

- message is not inc3.atlec? in the error count. 

1 - tne error count is incremented by one, and a ^-3 appears on the 
messaqe . 

2 - the error count is incremented by one, and an T appears on the 
message. 

If specxfied areater than 2, it is automatically set to 2- 

Def a ult : i severity code associated with the specified message 
nuikiber is used (shown in Table 1) . 
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Fessaa-3 
number 



f SC 1 
t 1 


mmm | 
1 


T 1 




1 -^ 1 


004 1 


1 "^ i 


001 1 


1 2 


001 1 


1 "-'* 1 


001 1 


f z 


001 f 


1 2 


001 1 


I 2 


001 1 


1 2 


001 f 


1 2 


001 1 


1 'A 


001 \ 


1 2 


G01 1 


1 •* 


001 \ 


1 2 


001 I 


1 2 


001 f 


1 2 


001 r 


1 2 


001 \ 


1 2 


00 i 1 


I z 


001 f 


1 2 


001 \ 


f 2 


001 1 


1 2 


001 f 


1 ^ 


001 1 


1 2 


f 001 1 


I "* 


002 1 


I -"^ 


002 1 


1 2 


002 f 


1 2 


1 002 1 


1 2 


002 1 


1 2 


002 1 


1 2 


002 f 


1 2 


002 I 


1 2 


002 1 


1 2 


I 002 1 


1 2 


002 \ 


1 2 


1 002 » 


1 2 


1 002 1 


1 2 


002 1 


I 2 


1 002 f 


1 2 


1 002 1 


1 2 


002 1 


f 1 


f 025 1 


• 2 


f 002 1 


1 2 


1 002 \ 


\ 2 


\ 002 1 


1 ^ 


1 067 f 


I 2 


1 002 I 


I 2 


1 006 f 


t 


1 024 1 


1 1 


[ 013 1 


1 1 


j 013 \ 


! 2 


\ 014 1 


1 1 


1 015 1 


f 


1 050 f 


» 2 


1 050 1 


t 


1 050 1 


1 1 


1 051 1 


f 1 


f 053 r 


1 1 


[ 056 \ 


1 1 


I 056 1 



Fessaae x-ext 



1 

3 
4 

S 
6 
7 

S 
9 
10 
13 
14 
15 
17 
13 
1:^ 
z1 
22 
23 
24 
25 
^' 28 
31 
35 
36 
37 
33 
39 
40 
1,2 
44 
45 
46 

m 

46 
4y 
50 
51 
54 
55 
56 
57 
58 
59 
62 
63 
69 
73 
85 
86 
37 
38 
69 
90 
147 
157 
159 
162 
163 



?^QUIB3D OPBBJ^ND (S) HOT SPSCIFI^D 

FIRST OFEHIl!fD RFQ»D-!IOT SPFCIFIFD 

S^CO-HB O^ERA^B HFQ*D-HOT SPECIFIED 

THIPD OPHr^T^IlI) PEQ«D-HOT SPECIFIED 

rOURTrl OPERAND HFQ»D-^01 SPECIFIED 

DC3 O^ERA^^D HEQ«D-JOT S"OECIFIED ' 

DECB OPSPAHD FEO»D~-!IOT SPECIFIED 

KEY OPERAND RE0'D-:!lOT SPECIFIED 

FIFTH GPERAilD RE0»D-MOT SPECIFIED 

LOW. LIE. OPERAND PEQ«D-HOT SPECIFIED 

AREA OPERAND RE0»D-SOT SPECIFIED 

LE1GIB O^ERA^iD RE0»D-JOT SPECIFIED 

VALUE OPERAND REQ»D-^OT SPECIFIED 

MODE OPERAND RE0»D-:?OT SPECIFIED 

HEGISTER^ OPERAND REQ»D-:iOT SPECIFIED 

MESSA^^E OPEBAirD P^Q»D-HOT SPECIFIED 

!IA^!E Of DCE REQ'D-^OT SPECIPIED 

HM.E OF ADCO^ REQ»D-^OT SPECIFIED 

HAHS OF CSECT PEQ"D-NCT SPECIFIED 

NA'IE 05 L FOR?* REQ»D-^OT SPECIFIED 

TI^E OF OPERAND REQ«B-^OT SPECIFIED 

CODE OPEFAIiDA^D FEC>»D-!10T SPECIFIED 

EP OR EPLDC OPERA^ID REQ»D-JOT SPECIFIED 

i:f¥ALID F^ OPERAHD S^ECIFIED-opva 

IWVALID FIFST OPERAND SPECIFIEb-oi;>va 

1!^VALID SECOND OPERAND SPECIFIED-opva 

INVALID THIRD O^ERA'ID S^ECIFIED~oi>va 

INVALID FOO'RTH O^-EEA^ID SPECIFIED-opva 

IS^^ALID FIFTH OPERA^TD SPECIFIED-opva 

I^^ALID EP OR EPLOC O^ERA^D SPECIFIED-opva 

IM^ALID L^HGTFi OPFfASD SPECIFIED-opva 

I)JVALID MODE OPERAND SPECIFIED-opva 

INVALID RE3 (S) OPERAID SPECIFIED-opva 

INVALID APEA OPERAND SPECIFIED-opva 

INVALID TYPE OPERAND SPECIFIED-opva 

INVALID OPTION OPERAND SPECIFIED-opva 

INVALID OPTIOM 1 OPERAND SPECIFIED-opva 

INVALID OPTION 2 OPERAND SPECIFIED-opva 

INVALID KEYWORD OPERAND SPECIFIED-opva 

INVALID REGISTER NOTATION SPECIFIED-opva 

PACK OPERAND NOT ALLOWED W/MODE=R 

INVALID ^R OPERAND SPECIFIED-opva 

INVALID PACK OPERAND SPECIFIBD-opva 

LV OPERAND RE0»D-NOT SPECIFIED 

ADCOND fACRO PREVIOUSLY SPECIFIED 

INVALID TAi CHARACTER CODE OPERAliD SPECIFIED-OOVa 

REGISTER NOTATION INVALID li/MF=L 

CSECT NAFE BLANK. FACRO NAFE OriTTED. 

!1ESSAGE OPERAND NOT ALLOWED W/«F=E 

OPLIST OPERAND NOT ALLOWED i/HF=E 

DECB NOT SPECIFIED AS SYMBOL 

MORE THAN ONE OF E? OP EPLOC PRESENT 

opnm OPERAND INCONSISTENT WITH TYPE=opvaopvb 

oonm INCONSISTENT W/oova OPERAND 

opRH OPERAND I1*C0NSISTENT-IGN0RED 

INVALID CODE FOR opnm-IGNORED-opva 

INVALID CODE FOR DSORG-IGNORED-OPva 

MACRF INVALID WITH SPECIFIED DSORG-IGNOFSD-opva 

EXIST INVALID «ITH SPECIFIED DSORG-IGHORED-opva 



I Table 1. Error messages issuei by CHDERMAC (part 1 of 2) 
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I' 

I Message 






■» 


1 nimber 


sc 


i Dam 


Kessage text 1 


1 166 


1 


060 


INVALID CODS FOR D5?D WITH SPECIFIED DSOFG- 1 
IGHORED-opva 1 


f 167 


1 


065 


HACHF INVALID-IGNORED-opva \ 


1 169 


1 


067 


DCSD MACPO PEEVIOUSLY OSED \ 


f 173 


\ 1 


[ 062 


DD^AME LO!fG-TRUNCATED TO 8 CHAR | 


I 174 


1 1 


1 070 


devd=oovb IGNORES opnm=ODva \ 


1 175 


1 


071 


INVALID opnm OPEPAHD SPECIFIED-IGMOFED-ODVa | 


1 176 


1 


072 


MULTIPIE DEVICE-DEP- PARAM - 1 SPECIFIED- 1 
IGfORED-ODva=oDvb 1 


\ Ml 


1 


073 


MULTIPLE DEVICE-D'^P. PAEAM . 2 SPECIFIED- | 
IG!JORED TRTCH=opva | 


1 178 





074 


PAD OPERAfD GT 50-SPECIFIED VALUE USED-opva | 


1 179 





[ 101 


CSECT OEIGIll USED FOE opnsi ECON | 


f 180 


1 


003 


opurn OPERA!ID INVALID OR MOT SPECIf lED-SET TO opva f 


f 131 


1 1 


1 076 


3PI CMTR IlfDICATES WRA^ AROUND TO TOP OF CRT 1 


1 182 


1 


\ Oil 1 


BLC GPEATEF THA!T OE EQUAL TO BLIM f 


f 183 


1 


002 


opnm INVALID-SET TO opva f 


1 134 


* 


] 078 


* CURREMI BUFFER opnro=opva f 


1 185 


♦ 


079 1 


* CURFENT BEAM POSITION COUNTEP IS X^OPM , I = opva f 


1 1S6 


1 


080 


opnm COUNTER EXCEEDS CRT LIMITS \ 


\ 137 


1 


031 


LOAD VARIABLE SPACE ORDER f^AI MOT HAVE f 
BEEN SPECIFIED PEIOF TO ENTERIMG STROKE ?!ODS | 


1 188 


2 


103 


opnn MACRO !IOT ALLO'^ED FOR PRIVILEGED USES | 


1 139 


[ 2 


f 103 1 


OT>nia FACE nOH ALLOWED FOR lONPRIVILEGFD USES f 
(SETTDE) 1 


f 200 


1 


101 


ZERO OSED FOR opnai RCOM f 


1 201 


) 1 


1 075 


VAR OPERA ID SOT ALLOWED W/FODE = B 1 


\ 210 1 


2 


001 


opim OPERAND EEO»D-MOT SPECIFIED | 


f 211 


•2 


f 002 


INVALID opnm OPERAND SPECIFIED-ODva | 


[ 212 


2 


001 


m¥E OF B^KD EEQ•D-^IOT SPECIFIED' f 


\ 213 


2 
1 


001 1 


TOO MAKY OPERANDS SPECIT'IED \ 


|Key to £ 


ibbre^ 


riatioi 


ie: 1 


1 opni] 


a = o| 


>eraiiid 


name opva = outer operand 1 | 


\ sc = 


= severity code opvb = outer operand 2 \ 


\ mmm 


= en 


:or mes 


3sage nunber odvc = outer operand 3 \ 



Table 2. Error messages issued b? CHDERKAC (oart 2 of 2) 

Execut ion : For any specified message niiraber, an M^.OTE instruction 
generated to produce an error message of this form: 



nnnnnn (b*sc+S) ***CHDffimm text 



where: 



CB*sc+3) is the severity cole. 

B is set e^ual to zero if the S= operand is present or to 

1 it it is not present. 
sc is the defaulted severity code shown in Table 1. 

S is the severity code operand; if it is not present, 

zero is used. 
nnnnnn is the six-digit line num,her of the ir.acro instruction 

for which the •'I^OTE is generated. 
mam is the error message number shown in Table 1. 

In general, you shoul-3 attempt to continue processing a macro expan- 
sion after detecting an error and oeneratina a niessaae. However, 
although it is difficult to generalize, soms errors should cause termi- 
nation ot Drocessina- An examole is an invalid FF operand in an S-tvoe 
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macro instruction ^ which makes further processing impossible. Inother 
instance is the occurrence of an error that propagates other errors. 

CHDPSECT — Res e rve Storage for P ar ameter List (0) 

The ChDPSECT inner macro instruction establishes the next available 
location in the user's PSSCf as the location at which the parameter list 
will be located. If no PSECT 2xists when the macro instruction is beina 
assembled^ the next available location in the current control section is 
used^ and CHDPSECT generates a branch around the list. 

i ^ — I 1 1 

J Name | Operation | Operand I 

I 1 —4- 



[[symbol] I CHDPSECT |[ location ],[ alignment ][ , string ] | 

I 1 1 ^ — ^ 1 

symbol 

is the symbolic location of the first byte to be assigned to the 

paraaeter list. 

Sp ecifi ed as: One to eiqht alphameric characters, the first of 
which must be alphabetic. 

location 

specifies the location to which the branch instruction is to trans- 
fer control. 

Spec ifi ed as: A relocatable expression or register notation. 

Default; If this operand is omitted, CHDPSSCT establishes its own 
branch address based on the lenath of the strina specified in the 
string operand- symbols generated by CHDPSECT will be of the form 
CHDxS-SYSNDX where x identifies a uriiue symbol. 

note : If the location operand is omitted, the string operand aust 
be present. 

alianment 

specifies the alignment for the beginning of the parameter list. 

Sp ec,if i ed __as : 

OF - dlignaent on a fullword. 

Gli - alignaient on a halfworl- 

Def ault : ^o special alignment is performed. 

string 

speciries a character string, originally specified as an operand in 
the outer macro instruction, which is -co be placed, as is, in the 
parameter list. 

Sp ecix ied as: T!ie character string itself. (CHDPSECT gererates 
and stores X'27" to indicate the end of the string.) 

Note: When this operar/i is nox specified, the branch address must 
be specified in the location operan-f. 

P rogra mming ^otes: Ihe use of a CHOP to force alignment is generally 
inettective, since t-he pararueter list may be generated in another con- 
trol section (the PSECT) . Placing the CHOP instruction before CHDPSECT 
has no effect other than to align tne macro instruction. 
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I CH D¥AL -- Pete rffiine Tvpe Code 

CHB¥AL tests a paraiaeter »?■ and sets the GLOBAL S5TC syobol c:iDTYP 
to the type code of •?•, aB(3 returns i^ a register the value of 'P', or 

the address of •?•. 

^ 1 J 1 

l^ame lOoeration f Ooerand, ! 

I — ^ f 1 1 

f [symbol JfCKDV.1L rP[,Hl I 

I J I ^ I 



the symbolic parameter whose tyoe is to Be tested by ChDVAL 

Specified as: any alphaaeric strinq (baqiiining with an alpha 
character), or Fegister through 15. 

R 

the reaister that is to contain the value associated with P. 

Spe cifie d as: register - 15. 

Initialization : The macro using CHDVAL must have defined CHDTI^ as a 
global SEXC symbol. 

Return Data : The GLOBAL SEIC symbol CHLTY"^ will, on return, b^ assianed 
one of the following values: 

Code V alue of I'P Feaning 

C 3,^,0 P is a character, hexadecimal, or binary 

tyoe symbol. R contains the address of "^ 

U U, 3 ? is undefined or a self-defining tern. 

R contains the address of P. 

R register notation used Fegister notation. 1 is not changed. 

II H, Y ? is defined as one of the half word 

aligned tyoes. P contains the contents 
of the field defined by P. 

F &,F, V, R, Q,D Pis defined as one of the fullword 

aligned types. ?. cor tains the contents 
of the field defined by P. 

null none of the above Type code ¥as not one of the ones 

checked and expected. 

Examples : Assuming user has coded G3LC o CBDTYP: 

(1) symbolic parameter 

CHDVAL WORD, 15 
+ ST IS,^!!-!) On return CHDT1?=*F» and 

Eegister 15 will contain 
an '3 • - 

WORD DC F»9« 

(2) Register notation for P 

CHDVAL (5) ,15 
+ AIF (•caDTYP«EQ«R») On return CHDTY?=»R' 
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and Eeqister 15 has 
not been chanaed. 



n 5,^ C,1) 



rarCK — >iAi t for and Te st Comple tioE of an I/O^ Qperati oF. CR) 



liie CHECK macro instructior. (for BSAM ar^ IOF;EQ) waits for completion 
of an I/O operatior reouested by a READ or '#3ITE macro instruction for 
BSAK or by an lOREQ macro instruction for lOREQ, and df^tects any errors 
and exceptional conditions that may occur. If the I/O operation is coq- 

pleted saccessf ully , the program resumes execution at the instruction 
after the ChSCK macro instruction. 

liie user p.ust issue a CHECK to test the I/O operation associated with 
a 'lata event control block (DECB) before molifying or ^ reusing it. 



I T r 

fiaike fOperation f Operand 

|. , ^ 



|[ symool If CHECK 



I decb name 



decb name 

specifies the address of the data event control block (DECB) 
create! as part of the exoansion of a RELD or WRITE macro instruc- 
tion or furnished in the lORFQ macro instruction that is being 

checked. 



Specxfiei 



Register notation (1 throuah 12) , or an HI addresiE 



Initxaliz ation : If this itacro instruction is to be executed in a privi- 
leqed Eoduier the most recently issued DCL^SS macro instruction in the 
assembly must have specifies PRIVILEGED (see Appendix M) . Also, the 
address of a save area Eiust be placed in register 13 before this macro 
instruction is executed. 

Proqrama,inQ !^otes : The CHECK macro instruction must be used to test for 
coftiDletion of every EFa3, KRITE, or lORFQ . For each data set, the CHECK 
macro instruction must be issued in the same order in which the READ, 
iEITE, or lOPEQ was issued. A BS^.n CHECK oust be issued before the num- 
ber of outstanding READ or i^'RITE Eacro instructions exceeds the DCB5IC? 
count (specified in the DCB macro instruction) in the data control block 
for the data set. 

For BSA.^: As recuired, the CHECK macro instruction passes control to 
appropriate exits that are soecified by the user in the data control 
block for error analysis (SISAD) and end-of-data set (EODAD) . The 
CHECK automatically initiates volume switching for input data sets. 
Additional space for outout data sets is automatically obtained when 
current space is filled and another itRITE is issued. 

It the CHECK macro instruction tests a DECB that has not been posted 
as complete, the user's task waits until the event is completed - 

If the CHECK macro instruction tests a READ operation that attempted 
to gain access to a block after the last block of a data set had been 
read, control is passed to the end-of-data set exit (EODAD) whose 
address is provided in the EODAD field of the data control block. 
The task is abnormally terminated if an EODAD address is not sup- 
plied. Refer to Appendix C for contents of registers when the EODAD 
routine is entered. 
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If the CHECK macro instruction ietemines that the READ or WRITS op- 
eration was not completed correctly because of an I/O error ^ control 
is given to the user's s?nchronous error exit (SYMAD) routine. Refer 
to Appendix B. 

The BETIIR!! lacro instruction may be usei to return to the calling 
program from the SYS^D routine. The urogram may then proceed, if c^e- 
sired, as if an error had not occurred. For input, processing may be 
continued; for output, the data control block should be closed. 

The task is terminated if an error is detected by the CHECK macro in- 
struction and the user has not provided a SINAD routine. 

If the CHECK macro instruction detects an end-of -volume condition 
when processing a multivolume data set, processing continues with the 
next volume- If there are no additional volumes, the user's EODAD 
routine is entered. 

A hardware-detected incorrect -length block is not interpreted as an 
error by the CHECK macro instruction if format-U records or truncated 
blocks of forroat-F records are being read- To determine the length 
of the block actually read, the user can examine the channel status 
word (part of the status indicators oointed to in the DECB) after 
issuing the CHECK macro instruction. The first byte of a format-U 
record read backwards from lEagnetic tape may be located by the same 
method. 

Figure 3 lists the results of incorrect-length error in which the 
length of the record read is different from the DCBBLK for format-F 
and format-U, or the LL fiel3 for forma t-V. 



1 ■ , \ ■ I 

f Kecord Format (PECF^) | Control oassed to SYSAD f 


1 Fixed (F) \ Yes [ 


1 Fixed blocked (PB) | If block is short by a noniaultiole of \ 

1 flHFCL 1 
I 1 1 


( Fixed standard (FS) | Yes f 


1 Fixed block standard (IBS) I If block is short bv a multiple of | 
r ILRECL * \ 


1 Variable (?) f Yes f 


f Variable blocked (VB) f Yes 1 


1 Undefined (0) f No f 


f *If the blocK is short by a multiple of the record length (I.RFCI) , f 
1 the next record causes an end-of -volume condition. If the cur- | 
1 rent volume is the last of the data set, control is passei to \ 
I EODAD. li the current- volume is not the last, processing contin- I 
1 ues on the next volume. I 



Figure 3. Eow incorrect record length is handled 



f or l O REQ : If an lOHFO results dn a unit check or unit exceotion, 
the CHECK of the DEC3 associated with this lOEEQ causes control to be 
aiven to the user's SYNAD routine specified in his data control 
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block. If a linkage to SYMAD is executed by CHECK, all outstanding 
lORSQs are purged fro© the systen. In the user-provided SYNID rou- 
tine, the user may reference the DCBEC field to facilitate reissuina 
any purged lOREQ. k RETURN may be issued in a SYMAI) routine that 
causes control to be returned to the instruction following the CHECK 
that invoked the SYHAD routine. 

Upon entry to the SY1AD routine, register 1 contains the address of 
the DECB associated with the lOPSQ involved. 

I»hen a subsequent lORFQ is executed after the SYHAD routine is 
invoked, the contents of the area pointed to by DCBDEC in the data 
control block may be changed. 

If the DCBBEYD field is zero or defaulted, any unit check or unit ex- 
ception causes the CHECK of the aopropriate DECB to invoke SYHAD. 

Example : The CHECK macro instruction tests for completion of I/O opera- 
tions in the order in which they are reauestei. The operand field con- 
tains the name of the data event control block specified in the read, 
write, or I/O request. 



EXl REID I>IDSCB,SP,IHVE!I, WORK, 100 



CHECK IHDECB 



SX2 WRITE OuTDECB,SF ,!!:iTaR?RT , WORK , TOO 



CHECK OUTDECB 



EX 3 lOREQ IODKCB,S ,DCBAD ,VCCW AD , 10 ,: 



CFECK ' lODECB 



i CKCLS -- Cr>eck Protecrioii C lass ( R) 

I The CKCLS laacro iTistruct:ion enables you to check the laost restrictive 
f protection class assianed to a group of halfpages. 



f fj-ame f Orje ration I Ddb ran i 
4— h " 



f |[ £.y iibol ] ICKCLS |[s.tarting address ][ ,nun.ber of half pages ] 



i starting adiresr 

\ specifios i^he virtual storaore address of the first halfpaae you ■ 

I want to caeck- 

rart 2: Macro Instructions 66.1 
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Spe cif i e'3 as: An RX address, or regiEter Botatxon (1 thro^iah 12) . 
If register notation is used, the ad-'^ress Jdust be loaded into the 
specified register before issuing the macro instr'iction . 

Default : It- is assumed that ttie issuer has place' the S-T^pxtina 
address in register 1. 

number of halfoaoes 

specifies the nuuiber of consecutive half^aqes von want xo check - 

Spe cif ied__ as : An absointa' expression or register notation (0 ani 2 
through 12) . T'he eaxiraum rubber of half^aqes that raay be sDecifie-^ 
is 8192. 

Default : It 'is assamed the issuer has placed the information in 
register . . 

Execution : Consecutive halfoages starting at the address contained in 
register 1 and equal to the half page count contained in register are 
checked . 

Beturn Data : A code indicating the no.st restrictive protection class of 
the pages checked is returnod in the lotf-orler byte of register 0. One 
of these codes is returned: 

Code Protection Class 



Page unassigned 

1 User read/write (least re^^trictive) 
3 Dser read only 
7 User cannot read or write (Eost restrictive) 

Example : Suppose you 'rfant to check the protection class of the five 
half pages Deginning at HJG. You write: 

CKCLS RdG,5 

CL ATT --~ Giv e Syste ra Control of Attention Int errupriGns {OX 

The CLAII macro instruction allows the user to relinquish control of 
attention interruptions; the svsteE then processes attention 
interruptions. 

I 1 1 ^ ' ~i 

f 'flame f Operation | Operand f 

!_. Y^ !___ ^ , 

f[syiabol]fCLATT | I 

I I I ^ I 

Note : There are no operands - 

Initializ ati on: This macro instruction cannot be assembled in a orivi- 
leged module unless the most recently issued DCLASS macro instruction in 
the assembly specified USER (see Appendix K) or if the DCLASS option is 
USER by default - 

Programming Motes : This macro instruction is used in conjunction with 
I the USATT macro instruction, discussed in this section. 

I CLIC -- Bead Comman d From S YSIJ (Conditional) (O) 

I For conversational tasks only , control is oassed to the conmiand sys- 
I tern and txie user is given an opportunity to enter a comnand at his SYSI^T 
f terminal. 

66.2 
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f 1 ^ "I 

I }laye \ Doer a "Lion | Ooerand 
!_„ „„.| _ ^ 4- 

I [ syiiiboi 1 |CL J.C I 



E9.1^ • 'i i~^ sre are no o pe r a n^:^ s , 



Initializai,ioii : K DCLASS iBacro instruction ^jiith the USFR option must te 
colei (or defaulted) in a CSEC;? prior to coding CLIC. If more taan one 
DCLASS macro instruction is issued in a aiodule, the last DCLASS issued 
t>rior to couing CLIC must be issued with the USEB ODtion. 

F xecution : the CLIC macro instruction switches the task froi program 
itode to coksiand mode to allow the user to enter cofTiman-i!, s. Ihis macro 
instruction causes an unconditional pauS'3 in conversational moda and is 
disregarded in • non-conversational sode. Any coiamands may be issued. 
The task can be switched back to runnina the Drogram by issuing the RUF 
coiiiiaand . 

Example: at any point in the orogram you want to pause ^ write: 

CLIC 

CLIP -- E eal Cum man l Fr oiti SYSl'l (nnconlitional) ( 0) 

For nonconversatioDal or conversational tasks^ control is passed to 
the coma.and system and the next command is read from the user's SY3IH 

device . 



|!!laii!e lOperation lOperand 



f [ symbol ]f CLIP 



^ote : Ihere are no operands. 

Initizili zat ion : k DCL.ISS aacro instruction witn the USEE option must be 
coded (or defaulted) in a CSECT prior to coding CLIP. If more than one 
DCLASS Bacro instruction is issued in a module, the last DCLftSS issued 
prior to coding CLIP must be issued with the DSEB option. 

Executio n : The CLIP macro instruction switches the task from program 
Eode to command aode to allow the user to enter coBEianis. Ihis macro 
instruction causes an unconditional pause, and executes whether the task 
is conversational or nonconversational- Jlny commands may be issued from 
the terminal during conversational proaram stoppage. If the stopped 
program is nonconversational, the SYSI^ data set vill be interrogated 
for the next commands. Ihe task can be switched back to program mode by 
issuing a HUH coil a and. 

Example : the Boint in the proaram you want to pause, write: 

CLIP 

Mote: The CLI^ macro instruction reads from the SYSI^ data set and does 
not require a terminal; CLIC reads only from a terminal and must, there- 
fore, only be used in a conversational task- 



CL OSE -- Disc oBBe ct Data Set from Ose r's t' r oblem Pro g ram ( S) 

Ihe CLOSE macro instruction disconnects one or more data sets from 
the user^s problem program. 

Part 2: Kacro Instructions 66.5 
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During the execution of CLOSE, the iiser^s trailer label routine, if 
supplied, will be given control (BSHM and QSAH only) . (R^fei^ to Appen- 
dix A.) 

Standard fora: 



I 1 1 

I Name {Operation fODerand 
I f f— 



I |[syHbol]|CLOSE | ({deb address ,[ {REEBID |LEI¥E fEUH] ]] , )[ ,TIPB=T] 

I I I 



L-f orm : 



1 f 

!laffie IDperation [Operand 

» 1 

[symbol] I CL0Si2 f ({deb address, [ {RER'^'AD f LEAVE fEU'f} ]) ,...)[ rTIPE=Tl 

\ I ,f1F = L 
I J 



Mote : A symbol is reguired in the name field. 
E-f orm : 



I 1 1 

I Name (Operation | Operand 
I 1 i-- 



f f[ symbol ]|CLOSE |[ ({acb address ,[ {EFL5AD | LEA VF f RU^] ]} , )] 

f f I I ,FE=(F,list) 

I I I 



Note: B-forE operands will overlay those specified in the L-fori. Wit 
MP=E, no more deb addresses may be soecified than were specified vith 
the L-forik CLOSE- 

dcb address (all access methods) 

specifies the address of the ^ata control block opened for the data 
set that is to be permaneatly or temporarily disconnected (closed) 
from the system. If more than one data control block is soecified, 
two commas must be placed between each address to indicate the 
omission of the repositioning option (see below) , even thoucrh it is 
applicable to 3SAJ! an'^ QSAH only- 

Specif ied ^as : In- the ?tandar3 and L-fori, as a relocatable ex-ares- 
sion ; in the standard and E-form, in register notation (? through 
f 12) ; in the E-form only, also as an RJ address. 

I REREAD I LEAVE I EUK (BSAM anl QSA1) 

specxfies the voluie repositionina that is to be performed as a re- 
sult of closing- This operand is applicable to volume disposition 
of magnetic tape devices only; it is ignored for other de^^ices. 



66.4 



PageofGC28-2004-6 
Revised 9 May 1979 
ByTNLGN20-3941 

Specified as : 

RERBID - tke current volume is positioned to process the data set 

again. 

LEAVE - the current volume is positioned to the logical end of data 

on the volume. 

RUN - the current volume is to be rewound and unloaded. 

Default: LEAVE 

TYPE=T (B£AF and VAK only) 

indicates that labels are crea^ed and volumes are positioned, but 
the fields of the data control block are not altered. The data set 
can be processed without issuing another O^FN macro instruction. 
If TYPE=T is designated, it applies to all of the associated data 
control blocks. 

After this macro instruction has been executed, the user's program 
can issue other macro instructions directed toward processing the 
data set because the data control block remains in OPE!l status. 

Sp ecified as : 1 Y P H = T 

Def ault : If this operand is omitted, the close is permanent (and 
the data set cannot be Drocesse3 without issuing another OPEH macro 
instruction) . 

Initializ ation : If this macro instruction is to be executed in a privi- 
leged nodule, the most recently issued DCL'SS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M) - Also, the 
address of a save area must be placed in recrister 13 before this macro 
instruction is executed. 



CAUTION: 



Errors shown in Figure 4 cause the results indicated. 



1 Errors 
1 




Result 1 


r 

I PermaneBtly or temporarily closina a lata control 
1 block that is not open 


Ic action | 


1 

li'eiaiiorarily cj^osing (TYPE=T] 

fthat has not been ooened for 
1 


a 'lata control block 
3SAB or VA:i 


^lo action | 


f 

1 1-erFianeri tiy closing when the 
fnot specify the address of a 


icb aidress ooerani does 
data control block 


TasK. tereinatedl 


1 

|l-enporarily closing (T^PE = ld 
(operand io-^^s not specify the 
f block 


Hhet) the Ich address 
aidress of a data control 


Unpredictable f 


1 

1 Pera^anently closing a iata control block containina 
fan invalid DSORG specification 


Task terminated I 



iiaure 4. Results of errors in closina a data set 



ProgramDiLq, Jiotes : Any nuBber of data control block addresses and asso- 
ciated options (BSAr and QShf) aay be SDecifiel in the CLOSE macro in- 
struction- This makes it possible to close data control blocks and 
tkeir assocxated data sets in parallel, which is more efficient than to 
close them individually. 
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YAB OBly 

I'iie CLOS"^ iiiacro instruction releases any sharing interlocl^is set 
for the lata set- Rules for sharing ¥Art data setf are aiven in Ad- 
pendix K. 



If Eore than one data control block is specified in a CLOSE ifiacro 
instructioii for VAM lata sets, two commas rcust be olacei between each 
to indicate the omission of the repositioning ooerand, which is ap- 
plicable to BSAM only . 



When 'a CLOSE 
directory pages, 
wrinren to exter 
tion on external 
external storage 
tionel data sets 
OPEM option and 
CLOSE {1YP2=1) . 
for vhich a fl^D 
normal CLOSE. A 
tne senber is su 



CTYP?=T) is specified for a ¥AH lata se 
and data set control blocks, where reg 

nal storage, ensuring that lata set con 

storaqe reflects the contents of the d 

The data set remains i?. OPEM status. 

are positioned (via SBiL) according to 

data set organization prior to the coB^p 
when partitioned data sets are process 
has been issued are stowed fSTOK type 
FIND macro instruction must be issued 

bsegueiitly to be reprocessed. 



t, ■I'ata pacre 


r 


Gired, are 




trol inforna 


- 


ata paqes on 




ionparti- 




the oriqina 


1 


let ion of th 


e 


edp 'n:eBbers 




H) as during 




by the aser 


2_ 



BSAM and QSkn onl y 

The CLOSE ITYPE-T) ©aero instruction aay be used to iisconnect 
temporarily, from the problea Program,, one or more data sets if the? 
reside on magnetic tape. An OPEH macro instruction Must nave been 
executed for each data control block, specified in this for?- of the 
CLOSjs macro instruction. 

When ti*e data sets are tea,porarily disconnected, labels are pro- 
cessed and user label exits are taken, if necessary. Magnetic tape 
volumes are repositioned as specified in this macro instruction - 

Hagnetic tape positioning varies dependincr on the options chosen 
in OPEM and CLOS"^ (TYPE=T) macro instructions and on whether the data 
set uses labels. Figure 5 defines a final position number for 
labeled and unlabeled taoes and Jigure 6 relates the options chosen 
in OPEN and CLOSE macro instructions to oositioning or tape volumes. 

User trailer-label exits are taken for a data set processed for I^ont 
or OUTi!! if the last operation was a hRlTE. No user trailer label exits 
are taken if tne last operation was a RE^D. 



Position 



Labeled Tape 



f Onlabeled Tape 



Preceding data set 
header label group 
on current volume 



Preceding first data block of 
portion of data set resident on 
current volume 



Foilowina tape mark 
that terninates 
trailer label group 
of data set on 
current volume 



Following tape mark that terminates 
last data block of portion of data 
set resident on current volume 



Figure 5. Final magnetic taoe oositions 
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option 1 of 
OPE:^ speci- 
fied as 



Oxher Factors 

Influencing 

Positioning 



fbirectioii of 
fLast Ii?i:^ijt 
f Operation 
! 
I 
_l 



fGlume reDositionmq 

a.£ S'peciried in 

CLOSK 



L^AVB 



7 P 



READ 



OUi?U^ 



:iot aBnlicable 



-+" 



0U2IH 
{BSir only) 



I Not aeteriaining 
f factor 
^ 



C3SAW orly) 



At least one w'SITFfLlot determining 
o Deration in this | factor 
data set f 



Posixion z 



Posirion 1 



^~- 



INPul 



Forward 



~h 



INOJT 
(BSAF onlY) 



}1o fcRITE operation I Porvar-I 
executed in this f 
^"iata set \ 
f 



HDdACK 



J Forwarl 
-I 



.NPUT 



I backwar-^ 



IS OUT 
(BSA:i only) 



!lo WRITE operation f Backward 
executed on this | 
data set \ 



Position 1 



Position 2 



RD3ACK 



f Backward 



Figure 6- Factors deteriinina magnetic tape positioning in BSAH and 

QS^F. 

If the data set resiles on a maanetic tape, the following concerns 
the writing of trailer labels: 

1. If the data set was opened for OOTIM or IHOUT and the last I/O op- 
eration was a kPITE, then CLOSE or CLOSE (TYPE=T) both cause trail- 
er labels to be written. If CLOSE (TYPE=T) is issued, additional 
READ or WPITE macro instructions are accepted without issuing a new 
OiSN aacro instruction. 

2. If the data set was opened for OUTI^ or I)IPUT and the last I/O op- 
eration was a ll~^.kl), and then a CL0S5 or CLOSE (TYPE=T) was issued, 
additional READ and ^BITE macro instructions are accepted without a 
new O^SJ macro instruction being given. 

3. If the data set was opened for OUTPUT, a CLOSE or CLOSE CI?PE=T) 
each cause trailer labels to be written. If a CLOSE CTYPE=T) is 
issued, additional WRITE macro instructions are accepted without a 
new 0?E!J macro instruction being given. 

4. If the data set was opened for I'^PUT or HDBICS, a CLOSE or CLOSE 

(TI?E=^T) does not cause trailer labels to be written. If CLOSE 
(TYPE=T) is issued, additional READ macro instructions are accepted 
without a new OPES macro instruction beina given - 

L- and E -Form U se: The format of the parameter list generated by the 
CLOSE macro instruction is described in Appendix L. 

For example: 
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EX1 


CLOSE 


SX2 


CLOSE 


EX 3 


CLOSE 


EX4 


CLOSE 


EX5 


CLOSE 


For VII!: 
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JOE CLOSE C»DCB,^BDCB^,) ,HP=L 

fBRI CLOSE (, ,PHODCB,,AXBCB) ^MF=CE,JOB) 

When the E-form macro instruction is executed^ the data control block 
PRODCB replaces the data control block &DC5 in the parameter list, and 
the data control block AXDCB is added tc the parameter list in the posi- 
tion reserved by the two commas following BDCB in the L-form. Thus, 
data control blocks with symbolic addresses ADCB^ PRODCB, and &XDCB are 
closed. 

Erait ftle s : 

For BSAF or QSAK; 

EX1 closes the data set associated with data control block IM?E^ with 
no repositioning. EX2 closes the two data sets associated with c'ata 
control blocks IHVEN and BEPOET with different ootions. EX3 closes 
data sets associated with two data control blocks. Since the volume 
repositioning option is omitted in EX3, volume disposition is 
defaulted to LEAVE- EX4 generates a Parameter list for closing 
IMVEN, and EX5 closes laVEN. 

(IfVEH^LEAVE) 

(IIIVE^, LEAVE, EEP0PT3EPEAD) 
(T}JVEN,,HASTEH) 
(IHVEW, LEAVE) 
ME=(E,^X4) 



EX1 closes data sets associated with two data control blocks- EX2 
generates a parameter list for closinq I'JVE'i, and EX3 closes I'iVEM. 

(IF?EN,,MASTEE) 
(INVEN) ,HF = L 
HF= CE,BX2) 

CHTBL — Control 0n~Line fape Drives (R ) 

The CNTRL macro instruction (for BSA^I) performs repositioning opera- 
tions on magnetic taoe ririves. 

I 1 ' 1 1 

IHame lOperation f Ooerand f 

I 1— , , 

J[ symbol ]fC^TRL f deb address, action[ , number ] I 

I . 1 L__ 1 

deb address 

specifies the address of the data control block opened for the data 
set beicg processed. 

t Specified as : Register notation (1 through 12) , or an RT. address 

action 

f specifies the positionina to be performed. 

Sp ecilied as: One of the three -character codes ir Figure 7, or 
(0) , in which case on^ of the abbrevialel two-character co5es must 
De placed in the tvo high-order bytes of register before this 
macro instruction is executed. 
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EX1 


CLOSE 


EX 2 


CLOSE 


EX 3 


CLOSE 



T r 

Abbreviated 
Code 



Code 



Effect 



BSF 
BSK 

B3R 



ERG 
PS? 

FSF 



FSR 



BF 
BM 

BE 



EE 
FF 

FK 



FR 



A number 



Moves backward past a taDemark 

operand of 1 is assumed. 

fioves backward past a tapemark and forw 

spaces over the taDemark. A namber ope 

is assumed. 

BacksDaces over a number of blocks on m 

tape, the number of blocks being specif 

the number operand. One block is assum 

number operand is omitted. 

Executes an erase gap for magnetic tape. 

Moves forward past a taoeraark. A number operand 

of 1 is assumed. 

a taoemark and backs 
A number operand of 



ard 

rand of 1 

agnetic 
ied bv 
ed if the 



EE^' 


FW 


W2-Ii 


k!i 


RU!I 


BU 


SHS 


f SN 



foves forward past 
over the tapemark. 
assuicei. 

Forward spaces over a number of blocks 
netic taoer the number of blocks being 
by the number operand. One block is a 
the number operand is omitted. 
Fewinc^s magnetic tape. 

Writes a tapemark on magnetic tai>e. A 
operand of 1 is assumed. 
Rewinds and unloads magnetic tape. 
Obtains sense information on the tape o 
access device for the data set being pr 
(a pointer is returned in register 1 to 
containing the sense information in DEC 
to 3 bytes of sense data will be read a 
to device type currently in use- Unuse 
bytes, will be returned as binary zero. 



Daces 
1 is 



on mag- 
specif ied 
sumed if 



number 



r direct 
ocessed 
a DEC3 
ASB) . Up 
ccording 
d sense 



Figure 7. Tape control options 



number 

specifies the number of blocks to forward space or backspace on 
magnetic tape . (as specified by the action operani) . 

Soecilied as: K oositive decimal inteqer, maximuiB 32,767. Alter- 
natively, (0) may be soecified for the action ooerand and the num- 
ber may be placed in the two low-order bvtes of register before 
execution oi the macro instruction. The parameter register is used 
only if the action code is specified in the hiqh-order bytes of the 
register. 

Default: If BSR or FSR is specified for rhe action operand, the 

default for the number operand is 1 - If the action cole specifies 

3bF , 5S1, FSF, FSM, WTr*, or SWS, xhe system uses a nu&ber value of 

1 no ikatter what is specified by the user. 

C a liTIDHS : If maonexic taDe Dositioning is performed, an uncorrectable 
tape-spacina error results in linkacre to the user's SYNAD routine; this 
does not apply no action codes PEW or PUM. Refer to Rppendix B for a 

discussion of SY^AD. 

AbriOrmal termination occurs if: 

1. The action code is undefined or not applicable. 

2. An operation is attemoted for an invalid device type. 
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3. A SYMAD-tvpe error occurs and the user has not proviied a SYlkD 
address. 

4. The data control block specified by the user has not been valiily 
opened . 

5. A repositioning operation is attemoted after a Dermanent: error - 

6. I'he reTuesred operation did not succeed - 

Initializatxon : If this macro instruction is to be executed in a privi- 
leged module, the nost recently issued DCLiSS aiacro instruction in the 
assembly musi: have soecified PRIVILEGES (see ADpendix ?!) . illso, the 
address of a save area must be placed in reqister 13 betore this macro 
instruction is executed- 

Return Data: It the repositioning operation is successful, register 15 
contains binary zeros; otherwise, it contains, in its two lo»f-or.ier 
bytes, a count of the resaioing nuaiber of forward soaces or backspaces ' 

that (lere not completed. 

Programiiiing 'aotes : RE^D and WRITE operations must be checked for com- 
pletxon before the CNTEL macro instruction is issued - 

Control is returned to the user if a tape mark or a load point is 
encountered during an attenpt to forwar-i space or backspace blocks; con- 
trol is not passed to the SYNAD routine - 



COMMAND — Ent er Co ittE and Mo de fP) 

The COFFAMD macro instruction switches the task from proqran mode to 
coEimand mode to allow the user to enter commands. This macro instruc- 
tion causes an unconditional pause, and executes whether the task is 
conversational or nonconversational. Any commands may be issued from 
the terminal during conversational prograa, stoppage- If the stopped 
program is nonconversational, the SYSIN data set will be interroaatei 
for the next commands. The task can be switched back to proaram mode by 
issuing a KU^J coomand. 

The word COMMAND followei by the optional iLessaqe specified is writ- 
ten on SYSOUT. 

r- 1 1 1 

fliaiiie lOperation (Operand f 

I- h- h 



|[ symbol ]|COPFAND ({address of messagaf »iiessaae*} 



address of message 

specifies the location of the message to be written (see below) . 

Spe cified as : Register notation (1 throuah 12) or an RX address of 
the location that contains the message as a character string. The 
first byte of the message must contain the length of the message 
(in bytes) . 

message 

specifies the message to be issued. 

Specified as; The messaae itself, enclosed in apostrophes. 
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Initia lizat ion : This macro instruction cannot be assembled in a privi- 
leged module unless the most recently issued DCLASS macro instruction in 
the assembly specified USEE (see Appendix n) or if the DCLASS option is 
USER by default. 

P rogramming Note s: If the user has control of interruptions before 
issuing a COKKAND macro instruction, the system regains control until a 
RUN command is issued. 

E xamples : In EX 1 the message is supplied as text- In EX2 the message 
is given at location BEMEL. 

EX1 COMMAND •PROG IN SUBRTN SGROOT* 
EX2 COKKAND BEMEL 



C QNSEG - ~ Connect Di sconnect ed Seqme nt Gr o up [£ J_ 

The CONSEG macro instruction connects to an unassigned portion of a 
user's address space,, a disconnected group. The disconnected name is 

deleted. 

L-f orm : 

I ^ — I 1 ^ ^ 

fName | Operation ^Operand 

I 1 ^ 

I I symbol |CONSEG | [ DSNAMB=,RN AME= ,[ MF=L 

I I I 



E-form : 



I 1 — ^ — ' 1 

IName f Operation fOperand 

I ^ 1 .. 



f ^[symbol] fCONSEG f[ DN AKE= ,RNAKE = , ADDRESS = , ] KF=C,list) 

I i ^ I . 



Standard -form: 



, J J 

Name | Operation fOperand 



f [symbol] fCONSEG fDMKE=[ ,RNAHE=,ADDHESS=] 

I ,1. . I 



Note: All operands are keyword. 

DNAHE= 

specifies the eight character EBCDIC name of a disconnected segment 
group to be connected. 

S pecifie d as: name enclosed within apostrophies; in E or standard 
form only, as ^he address of DNAEE expressed as a relocatable ex- 
pression, Rx address, or register notation. If register notation 
is used, the register specified must be the first of a set of 
paired registers containing the disconnected segment group name. 

Default : None- 

CAUTIQN : DNAME must be specified in standard form. DNAHE must be 
specified in L-form and/or E-form macros which form an executable 

group. 
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Any user specified DNAKE beginning with SYS will be rejected by the 
system. 

ENAME= 

specifies the eight character EfaCDIC name to which the disconnected 
segment group is to be attached . 

Specified as: name enclosed within apostrophies ; in E or standard 
form only, as the address of RNAME expressed as a relocatable ex- 
pression, Rx address, or register notation. If register notation 
is used, the register specified must be the first of a set of 
paired registers containing the reserved segment group name. 

Defaul t; If this operand is omitted, the system will connect the 
group at the disconnected address if at disconnect time BO0!ID=Y was 
specified; otherwise, the group will be connected at any unassigned 
contiguous space available in the user's address space. 

C AOTIOH ; If the group was disconnected with BOUND=y, operands 
RMAKE and ADDRESS are ignored. 

Any user specifiea RNAME beginning with SYS will be rejected by the 
system. 

ADDRESS= 

specifies the segment aligned relative address to which the discon* 
nected segment group is to be attached. If RNAME is specified, 
address is the relative address offset from the beginning of RNAKE. 
If ENAME is not specified, address is the relative address offset 
from zero (i.*^-, an absolute address) . 

Specif i ed as: In the E or standard form only the address of 
ADDRESS, expressed as a relocatable expression, Rl address, or 
register notation. 

Default : Relative zero. 

CAUTION : If BOUND=Y at disconnect time, ADDRESS and RNAME will be 
ignored at connect time - 

Ret urn Data; On return from execution of CONS EG all defaulted 
operands will be filled in with system assigned values. The 
address field in the naiaeseg parameter list will be set to an abso- 
lute address. Register IS will contain a return code describing 
the success of the operation. 

Ret urn Codes 

00 Successful 

04 RNAME Invalid 

08 DNAME Invalid 

12 Segment not available to user class 

16 Invalid address 

20 Segment group overlap 

32 Insufficient space available 

40 System error 

Register 1 contains the address of the nameseg parameter list. 
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Note: The DSECT, CHUMSG covers the nameseg parameter list. 

Proqramikinq not es ; The return codes in register 15 may be usei to con- 
struct a branch table to handle the varying results from execution of 
the CONSEG macro. 

Upon expansion of this macro, a set of input flags is constructed in the 
nameseg parameter list. They are: 

X*80" DMUKE Specified 

X»4D« RHAMF. SDecified 

X«20» ADDRESS Specified 

Upon execution of COHSEG, a set of output flaos will be constructed with 
the above values including: 

X»10» BOU^D=Y 

If BOUND=Y was specified at disconnect time. 

Caution : If the disconnected segment group being connected was speci- 
fied with &Oil^D = ¥ at disconnect time, operands RNAME and ADDRESS are 
f ignored. Also, the total area to which the group is connected must be 

I unassigiie^^ . 



I COPY PS 



Copy Existing Data Set (S) 



I The COtYDS xacro instruction copies a coiolete data set or one or 
I more members of a partitioned data set. The resulting new data set is 
I assigned the data set name furnished (as an operand) by the user. In 
I addition, COPYDS may renumber the lines of a line data set. A copy of a 
f member may be specified either as a new member of a Partitioned data 
I set, as a new data set by itself, or as a reolacement for an existing 
I member with the sake name. A VAM data set may be copied as (that is, 
\ become) a member of a partitioned data set. 



I Standara tors (see "Operand Strings" in Part II, Section 1) 



1 J , 

Ilaiife I Operation I Operan' 



[ syobol]tCOPYDS 
I 



{address of ot>eran-:^ string J 

•data set name 1[ (membar, . . .) ], 

data set name 2[ (member) ], 

[EFAS^=CY|N] ], [starting line], 
[ increment ][ ,REPLACF= (R (I) ]»} 



f L-form (see "ODerand Strings" in ^art II, Section 1) : 

I 1 1 

f riaae | Operation | Oparan i 

t h- + — ^ 

I Isymbol ICO^YDS \ »aata set name 1[ (member, ) ], 

It I I --^ata Sex naFie 2[ (iBenber) ],[ erasE= (Y |N} ], 

II I I [startina line],[ incre2tent][ ,BEi'LACE= [HII] ]»,MF=1 

I t i 

\ Eiil:£- ^ s/a>Dol is require-^- in the name field. 
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E-torm : 



I 1 1 ' 

I )laffie [Operation) Op^rani 



f[syiibol]»CO^YDS \ fF= (Enlist) 

L I I . 



address of oDerand string 

specifies the address of tae first ooerand in the operan-i striiio 
(see "Operand Strings" in Part II, Section 1) . 

Spe cifi ed as: Fegister notation (2 through 12) or a relocatable 
expression. ^cte that the operand strina can also be specified in 
the E-foriu macro operand as a character string enclosed in apos- 
trophes, as shown - 

data set name 1 

specifies the data set nane or the data set beincr copied- It i^iust 
be cataloaed or have been defined in a DDFF macro instruction or 
command. 

Spe cifi ed as: The fully oualified name of: 

• a data sen with one r^eiaber name or a list of i?e!^ber naaes enc- 
losed in parentheses, or 

• a data set with no members specified. 

data set name 2 

specifies the data set name to be assigned to the copy of the data 
set. Tne data set must ^have been defined in a DDEF macro instruc- 
tion or coEEand unless a member of a cataloged partitioned data set 
is specified. 

Spe cified as : The fully qualified name of: 

• a- data set with one member name enclosed in parentheses, or 

• a data set with no ineBbers specified - 

When the original and copy data sets are both partitioned a.nd no 
Bembar naae is specified in this operand, the meebers are moved 
from the original to the copy data set with user data and aliases - 
Duplicate meabers are processed as described under the RF'>iaCF 
operand. If a member name is specified, the original data set name 
must have exactly one member name specified; no user data or 
aliases are copied. 

ERASE= 

specifies the disposition of the original data set iienber or Mem- 
bers after being copied. This applies only to data sets on direct 
SLCcess devices. If a shared data set is to be copied and then 
erased, unlimited access to the data set must have been permitted. 

S pecified as : 
Y - erase original data set member after it is copied. 
N - do not erase original data set member. 

Default ; N 

starting line 

specifies the starting line number of the data set copy if it is a 
line data set and renumbering is desired- 
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Spe cif ieu. as: h three- to seven-digit number, the last two digits 
of wnich must be zaro. An all-zero starting line number is 
invalil- 

Det aul t : It incraient is also lefaulted, line numbering is not 
perfornel. li increment is not defaulted , the starting line number 
of the copy data set will be 100. 

increment 

specifies the value by which line numbers in the data set copy (if 
it is a line data set) are to be incremented when renuiRbering is 

desired. 

Si> eci£ ied as : A three- to seven -dinit nuiaber, the last two diaits 

of which must be 0. In all-zero increment is invalid - 

Det aal t : If the starting line nuiiber is also defaulted, line nuob- 
ering is not performed. If the starting line number _is not 
defaulted, an increiaent of 100 is assuciei. 

RE1LACE== 

specifies the disposition of the numbers of the oriainal data set 

thai, have duplicate naties in the co-oy data set. This operand is 

only used if user lata and aliases are to be copied. 

Specified as : 
R - the duolicates are to be replace!. 

1 - the duplicates are to be ianored . 

Default : R 

Initial izat ion: If this aacro instruction is to be executed in a privi- 
leged nodule, the most recently issued DCLASS macro instruction in the 
assembly must Lave specified PRIVILEGED (see Appendix M) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed - 

P rogramming Mot es: If both data sets specified are partitioned data 
sets and if the copy data set has no mernber name specified, the COPYDS 
macro instruction will copy: 

• one oei!i,ber of the original data set, 

• any number of members of the original data set, or 

• all the members of the original data set, if the original data set 
has no mefiber nanies specified. User data and aliases are also 

copied - 

When multiple members of the original data set are specified, the 
copy data set must be partitioned. COPYDS replaces an existing member 
of the copy data set with the member of the original data set. If a 
Eeaber of the original data set has a duplicate name already in the copy 
data set, the REPLACE operand specifies that the member is to replace 
the duplicate (HEPLACS=S) , or is to be ignored (REPLACE=I) . If an alias 
for a Renber of the original data set already appears as an alias for a 
different member of the copy data set, the member will not be copied, 
regardless of the REPLACE operand. 

Ihe COPIDS iBacro instruction does not differentiate between object 
modules and other members of partitioned data sets. For any member, 
user data and member name aliases are transferred along with the data 
and member name. 
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The COPYDS macro instruction is restricted to data sets on direct 
access or magnetic tape volumes. Data set organization is not altered 
by the use of a COPYDS macro instruction. The original and copy data 
sets must be defined with the same data set organization and record for- 
mat. For example, the copy of a physical sequential data set has i>hys- 
ical sequential organization, even though the device type may be 
changed, k VISAM data set can, however, be copied as VSAM and vice 
versa. 

The user may specify a VISAM organization in the COPYDS macro in- 
struction for a data set co^y, even though the oriainal data set oraani- 
zation is VSAM. In this case, each record of the original data set must 
contain a key. In addition, the user should define — in the DDEF macro 
instruction or command for the data set copy — the key lenqth (KEYLF'?!) , 
padding (PAD), and record key displacement (RKP) values. If he does not 
provide these values, no copy is made. 

The user can copy only those data sets that belong to him or those to 
which he has been given access. 

Return Data : At completion of execution of the COPYDS macro instruc- 
tion, the low-order byte of register IS contains one of the following 
hexadecimal codes: 

Code S ignific ance 
00 Successful completion 
04 Invalid input parameters 

08 Hame of oriainal data set not in catalog or task defini- 
tion table (TDT) 
OC Data set not in catalog and no DDBF macro instruction or 

command has been executed for it 
10 JFCB for oriqinal data set not consistent with JPCB for 

new data set 
iy ilemtar name not aiven for partitioned data set 
18 User does not have write access for new data set 
IC Original data set not VAK or S\n 

20 Data set not on direct access or tape; command ignored 

24 2lew data set member name already exists in POD 

28 Data set copied- Old data set not erased; user does not 

have proper access 
^C Data set copied. ^ew data set not renumbered; not a line 

data set 
30 Data set copied and renunbered. Old data set net erased; 

user dof^s not have proper access 
34 Data set copied and original erased. New data set not 

renumbered; not a line data set 
33 Data set copied; new data set not renumbered, an?, old 

data set not erased 

Examples : In EXI,^ the operands are presented as a character strina- In 
EX2, an address designates the location of the operands. 

BXl COPYDS 'DATASET,!!* 
EX2 COPYDS OPLISTC 

in EX3, the- original data set name is. v?l and has members A,B,C. The 
copy data set name is ¥P2 and has members C, D, and ^\, Following the 
execution of EX 3, VP1 contains C2 , and VP2 contains k, 5, the oriainal 
C, D, and E (C was not copied because the REPLACE operand specifies that 
members with duplicate names are to be ianored) . 

ET3 COPYDS 'VPI CA,S,C) ,VP2,ERASE=Y , , ,ES?LACE=I • 
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CSTORE — Control Section Store (S) 



The CSTOKE macro instruction enables the user^ during program execu- 
tion, to transform any set of contiguous virtual storage bytes into an 
object module consisting of a single control section. 

Standard form: 

I 1 1 ^ ' — ^ 1 

niame fOperation | Operand I 

I- 1 1 ^ 1 

|[ symbol] ICSTORl Jaodule nane, entry point name, data address, | 

\ I Jfiata length, attribute I 



L-iom: 



IName | Operation |Oi>erand 
I h— h 



I symbol fCSTORE |moiule name, entry ^oint name, [data address], f 
I I |[data length ],[ attribute], HF=I | 

I I 1 ^ 1 



Mote: A symbol is required in the name field, 

E-form: 



1 1 ^ ^ 1 

Same I Operation I Ooeran^ I 

»— -I— f 

[symbol] »CSTORE |,,[data address ],[ date length], ( 

I I[at:tribiite],f!F= (E,lisi:) f 

I I . I 



Mote : If an operand is omitted in the L-form, it must be specified in 

the E-form. 

module nacie 

specifies the naae to be assignei to the module created to contain 
the control section. 

Specified as : , i symbol (one to eiaht alohameric ^^ characters, the- 
first of which Hust be alonabetic) . 

entry- point name 

specixies the entry point name to be assigned to^ the specified 
address location. 

Speci£i€>d a s: L symbol (one to eiaht alohameric characters, the 
first of which must be alphabetic) - 

data address 

specifies the aadress of the first byte of data to be included in 
the control section. . 

Specified as : In the standard and L-form, as a relocatable -expres- 
sion: in the standard and E-tom , as register notation (2 through 
f 12); in the E-form only, also as an HI? addrass- 

data length 

specifies the nuiiber of bytes of data to be included in the control 
section . 

Spe cif ied as; An absolute expression; in the standard fore and in 
the E-form, regist-^r notation (z. through 12) - 
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attribute 

specifies 



the attribute byte of the control section. 



Specified asi Kn absolute expression; in the standard fora and in' 
the E-fors, also in register notation {2 throagh 12). The mearincr 
of the contents of the attribute oyte is shown in Fiaure 3: 



r 1 1 

f f Control Section Attribute f 


f Bit f Bit off 1 3it on I 
t 11 i 


1 » 1 1 

f 1 f system 1 
1 1 1 non privileged | onvileged I 

1 2 1 1 common | 
I 3 fCSLCT f Drorotyoe (PSFCT) f 
1 4 1 private | ouDlic | 

1 ^ S 1 read-write | read-only | 
J b 1 fixed-length | variable-length f 


f 7 not »ised \ 



Figure 3. Control section attribute byte 

Initializ ation : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified E^IVILEGKD (see iooendix K) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

Pr oqra iiming Not es: The module created: by this macro instructior is 
stowed ip the current JDBLIB- It can then be loaded by the program that 
created it, or by a subsequent program. When the Eo^ule is loaled, no 
relocation takes place; therefore, it may contain no relocatable items . 
The resulting module consists of an unramel control section that con- 
tains a copy of the hexadecimal text, beginning at the page boundary 
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worrespoT: lina to or pr^'^cedina the address rpecified as the startina 
address paraweterr and -LerRinatiag at the cage boundary corresnondiiicr to 
or folloifiiiq xLe aidrpss comouted from the fourth parameter. Thus, the 
resulrinq contro?.. section i.s always an inteqral number of paoes in 
lengrh. 

kLen tiie lEodule is loale3 by the user, the module name, as ¥ell as 
the entry Boint name, ooints to the address computed by addina to the 
load, address of the new module the page offset (if any) imoliei by the 
starting address. ior example, assunie that the user reouests that a 
control section of 4093 bytes be created from the bytes beginning at 
virtual storage address SDO*^0. Two pages of hexadecimal text beginning 
at tne oage boundary address (in this case 5D000) correspondina to or 
preceding the specified starting address are transformed into an object 
tt.odule- Ine module and entry point names are offset from the oage boun- 
dary by 50 to reflect the actual address (5D050) of the hexadecimal text 
which the user desires co olace in a control section. .Assuming that the 
new 3iodule is later loaleA at 700 00^ the loaded module and control sec- 
tion vill occuoy two full pages beainninq at 70000. The second Dage is 
required so taat the new control section will include the last two bytes 
reouestei bv the user. The new module and entry point names will be 
adjusted to reflect the offset and will both point to 70050. 

The maximum control section size is one segeent . The control section 

is created trom^. anv contiguous set of bytes, and is an integral number 
of pages in length. A control section is rot built if the module or 
entry point naies are daplic.ates of existino names in the current 

JOBLIB. 

Subsequent loading of the create 1 module is acco!!ii>lished implicitly, 
by using an R- and ¥-type address constant for the entrv point naae or 
module name, or explicitly, by use of the lO^D macro instruction - 

The coDiion attribute (bit 2) , if specified, will be ignored by the 
dynamic loader, since it treats all unnamed control sections as unioue. 
The created aodule may contain no relocatable words (adcons) and can be 
referred to by the control section name or laodule nane of f sets - 

Return Data : Upon comoletion of execution of the CSTORE macro instruc- 
tion, the low-order byte of register 15 contains one of these hexadecim- 
al codes: 

£21i^ Significance 

00 Successful completion 

04 Module naae or entry point name already in use 

Exaaple : This example indicates the macro instruction used to create a 
module named WYHODOLS which contains one unnamed control section- The 
control section consists of the two pages of text taken from the bytes 
beginning at HERE, which is on a oage boundary- The entry point name 
EPi!IAKK points to the beginning of the control section, which has public 
and read-only attributes. 

EXl CSTOSE P:YHODnii:,EPMAFE,HERE,3 000,12 

DCS — Co nstru ct a D ata Con trol Block ( 0) 

The DCa macro instruction is one of the major sources (see lopendix 
F) by which the attributes of a data set may ba described to the system. 
The attributes of a data set. that can be provided via this macro in- 
struction and the formats in which particular attributes can be speci- 
fied are indicated below by access method (for HSAK , see Sy stem Program- 
me r's Guide ) - 

Format : The format of the DCB macro instruction varies, depending on 
the data set organization and the diccess method that is to be used, or 
was previously used, to perform I/O on that data set. All of the possi- 
ble parameters that might be specified by a nonprivileged user in a DCB 
macro instruction are indicated by applicable access method in Figure 9. 
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Note that the operands can appear in any order r but must be in keyword 
form, separated by commas. 



I Name 

I 



I Operation \ Operand 



f- 



--1 

f (see figure below) 



f [symbol ]|DCB 
I I 



1 1 ' 1 

1 \ Applicable Access Methods f 


f Operands ^¥5 AK | VISAK J VPAH JBSAM f Q£AM JIOREQ f 


f[ ,DDNAKE=data definition name] rX|X fXfXIXfX f 


r[ ,DSORG=organizatioii,] f X 1 X | X | X f X | X f 


|[ ,RECFM=record format] rX|X fXfXfXf 1 


|[ ,LR£CL=record length] fXfX fXfX|Xf r 


J[ ,EODAD=end-of-data address] |XfX fXfXfXI | 


([ ,OPTCD=optional service] fXfX IXfXfXf | 


f[ ,SYNAD=^error routine] I f X f X* f X f X ( X f 


f [ ,PAD=a¥ailable space] f I X f X* f f I | 


|[ ,RKP=key field displacement] f f X f X* f | | | 


|[ ,DLVD=device] f f 1. f 1. | X | X f X | 


|[ ,KEYLLM=key length] \ f X f X* | X f | \ 


f[ ,TRTCH=recording techniaue] 1 | f I X f X J ( 


|[ ,P!ACRF=macro type] f r f > X J X f f 


|[ ,BLKSIZE=maxiauro block length] \ \ f 1 X f X f I 


r[ ,IKSK=error procedures] \ f | f X f I f X | 


f[ ,EXLST=exit list address] 1 f f | X f X J | 


|[,HCP=check number] I f f f S f \ X \ 


If ,BUFJIO=^nuiaber or buffers] 1 | | | X 1 1 ( 


|[ ,BFALM=buffer alignment] \ f | | X | I \ 


|[ ,BUFL=buffer length] f f f 1 X 1 I 1 


f[ ,BFT£K=buftering techniaue] ? \ J f X f | 1 


If rBUFCB=baf f er control block] f | | J X f f | 


f [ ,HSOPT=error option] II I | IX | | 
1 1 1 1 f 1 1 1 


1* - VISAf" ffi embers of a partitioned data set. I 
|1. = a value is assumed by the system- f 



Figure 9. DC3 operands and aaolicabla access methods 
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DDNjyyiE= Call access methods) 

specifies the symbolic data definition name associated with a par- 
ticular data set. This symbol provides the link that connects the 
attributes of the data set described by the DCE macro instruction 
with those specified by the DDEF macro instruction (or command), 
thereby providing the system with all the information necessary for 
processing the data set. 

Specified as ; A symbol Cone to eight etLphameric characters, the 
first of which must be alphabetic). The name specified for this 
parameter roast be identical to the DDNAME parameter of the DDEF 
macro instruction that defines this data set. The only alternate 
source for this information is the user's program. 

DSORG= Call access methods) 

specifies the organization of the data set. 

Specified as ; The codes by which the various data set organiza- 
tions can be specified, and the access methods with which they are 
applicable are: 

Applicable 
Code Organization Access Methods 

PS — physical sequential organization BSAM^QSAK 

PSU — physical sequential unmovable organi- BSAM,QSAJM 
zation in which the data set contains 
location-dependent information with 
respect to this data set. Treated as 
PS by TSS. 

^S ~ virtual sequential organization VSAM 

¥1 — virtual index sequential organization VISAM 

VP ~ virtual partitioned organization VPAM 

VIP — virtual index sequential member of a VPAM 
partitioned data set 

VSP — virtual sequential member of a parti- VPAM 
tioned data set 

EX — I/O request facility is being used lOREQ 

For an existing VP data set, only VP need be specified. The organ- 
ization of the member (virtual sequential or virtual index sequen- 
tial) is determined by FIND and placed in the ECB. However, when 
creating a new member, the user must specify either VIP or VSP. 

This information can also be supplied by the user's program or the 
DDEF macro instruction Cor command), but must he supplied before 
issuing an OPEN macro instruction. 

RECFM= (all access methods) 

specifies the format of the records in the data set. 

Specified as ; One of the following: 

For BSAM and QSAM ; 
OCT] [A|M} 
V[B|T] CA|W3 
F [E I S I T I BS I BT I BST | ST] [A | M3 
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Where the record format is: 

U — undefined- format records 

V ~ variable-length records 
F — fixed-length records 

Where the physical attributes ares 

B — blocked records 

S — standard data set| no truncated blocks or unfilled tracks 

T — track overf lo%^ employed 

Where the record contains: 

A — FORTRAN control character 

M — machine code control character 

If A or M is not specified ^ no control character is assumed. 

Refer to Appendix D for a discussion of control characters- 
Absence of any of the physical attribute mnemonics implies the 
opposite of that attribute. For instance ^ writing R1CFI«=V 
implies: variable-length, unblocked records, no control charac- 
ter, and no track overflow feature. 

This information can also be supplied by the user's program, the 
DDEF macro instruction (or command), or the data set label. 

For VAM data sets ; All VAM data sets can be organized as fixed- 
or variable- length records, but only VSAM and VPAM records can be 
specified as having undefined format. 

U[A|M1 (applicable to VSAM, WAM only) 

VIA I Ml (applicable to VSAM, VISAM, or VPAM) 

FCA|M1 (applicable to VSAM, VISAM, or VPAM) 

Where the record format is: 

U — undefined-format records 

V — variable-length records 
F — fixed-length records 

Where the record contains : 

A — FORTRAN control character 

M — machine code control character 

If A or M is not specified, no control character is assumed. 
Refer to Appendix D for a discussion of control characters - 

This information can also be supplied by the user's program, the 
DDEF macro instruction (or coirmand) , or the data set label. 

LRECL (VAM, BSAM, and QSAM) 

specifies the length in bytes of a logical record. For format-F 
records, this operand specifies the length of each record in the 
data set. For format-V and -0 records, the user must insert the 
maximum es^ected value before the data set is opened. When reading 
format-U or -V records, the corresponding field in the data control 
block (DCBLRE) contains the length in bytes of the record just 
read. 
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Specified as s i^n absolute expression. The maxiinura that may be 
specified for BSjyw data sets is 32,760^ the roaxirouro for ¥SAM is 
1,0^8,576, and the maximum for VISAM is 4000. 

This information can also be supplied by the user's program^ the 
DDEF macro instruction (or coirirand) , or the data set label. 

EODAD= CVAM, BSAM, and QSAM) 

specifies the address of the user's end-of-data routine for input 
data sets. This routine is entered if the user requests a record 
when there are no more records in the data set. If no routine has 
been provided t and the end-of~data condition has been encountered, 
the task is abnormally terminated. (Refer to Appendix C.) 

Specified as ; A symbol (one to eight alphameric characters, the 
first of which must be alphabetic). 

If the symbol supplied is an external symbol, it must also appear 
as the operand of an assembler language EXTRN statement in the same 
object module as the DCB macro instruction. 

The only alternate source for this information is the user's 
program. 

OPT(33= (VAM, BSAM or QSAM) 

specifies an optional service to be provided. 

Specified as : 

W- perform a write validity check i for direct access devices only 

A- ASCII tape request 

Default s No service is performed unless the code is specified from 
an alternate soiarce. 

T3iis infojcmation can also be supplied by the user's program, the 
DDIP macro instruction (or command) , or the data set label. If not 
supplied by any source, the service is not performed. 

syNAD= (VISAM data sets, VISAM members, BSAM, QSAM, or lORlQ) 

specifies the address of the user's synchronous error exit routine. 
The routine is entered if input/output errors result from an 
attempt to process data records. 

Specified as s A symbol (one to eight alphameric characters, the 
first of which must be alphabetic). 

If the address specified is an external symbol, the symbol must 
also appear as the operand of an assembler language IXTRN statement 
in the same program module as the DCB macro instruction. 

The only alternate source for this information is the user's 

program. 

Default ; If no routine is specified and the system encounters a 
condition that would cause control to be given to the SYNAD rou- 
tine, the task is abnormally terminated. 

PAD= (VISAM data sets or VISAM members) 

specifies the percentage of space to be left available within the 
pages of a virtual index sequential data set, thus providing for 
insertions within the pages. 

Specified as ; An absolute expression; the maximum value that may 
be specified is 50. 
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This information can also be supplied hy the taser's program, the 
DDEF macro instruction Cor coirnoand) , or the data set label, 

RKP= (VlShM data sets or VISAM niembers) 

specifies the displacement (relative key position) of the key field 
from the first byte of a logical record* 

Note ; For forroat-V records, the logical record includes the length 
field as the first four bytes, 

Specified as : An absolute expression. 

THiis information can also be supplied by the user's program or the 
DDEF macro instruction (or command). 

DEVD= (BSiMa, QBim, lOREQ, or VAM) 

specifies the device on which the data set resides. Additional 
keyword operands are available, as shown below, to provide device- 
dependent information to device-dependent parameter bytes in the 
data control block. 

Specified as ; One of the following codes: 

DA - direct access device 

lA - magnetic tape 

PR - printer (lOREQ) 

RD - card reader (ICREQ) 

PC - card punch (lOREQ) 

If DA is specified, KEYLEN may also be specified? if TA is speci- 
fied, TRTCH may also be specified. For VAM, DJ^ is assumed, and the 
user can supply the KEYLEN operand if desired. 

Note: Since nonprivileged users cannot address unit record devices 
directly, they may not specify PR (printer), RD (card reader), or 
PC (card punch). These devices may be specified only by users with 
proper system authorization. See System Programmer's (Suide . 

This information can also be supplied by the user's program, the 
DDEF macro instruction or command, or the data set label, 

KEYLEN= (VISAM data sets or VISAN members) 

specifies the length in bytes of the key associated with a physical 
record. When a record is read or written, the nxjmber of bytes 
transmitted is equal to the key length plus the record length. 
This operand is specified only if DA is specified. 

Specified as ; An absolute expression, maximum value 255. 

This information can also be supplied by the user's program or the 
DDEF macro instruction or command, 

TRTCH= CBSAM, QSAM) 

specifies the recording technique for 7-track tape. This operand 
is specified only if TA is specified. 

Specified as ; C,E,T,TE, or ET, where: 

C — Data conversion feature available. If data conversion is not 

available, only format-F and format-U are supported. 
E — Even parity is used. 
T — BCD to EBCDIC translation is required. 

This information can also be supplied by the user's program or the 
DDEF macro instruction (or command). 
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Defaults If not supplied by any source , odd parity and no transla- 
tion is assumed. 

Note: The system standard for 7-track tapes is Tl: even parity, 
BCDIC translated. 

MACRF= CBSAM and QSAM only) 

specifies the type of macro instructions to be used in processing a 
particular data set. 

Specified as ; One of the following: 

For BSJVM s 

(RtC|P]) 
CW[C|P]) 
CRtC|Pl,WlC|Pl> 

R — READ macro instructions 
W — WRITE macro instructions 

Optional modifiers : 

C — CNTRL macro instruction 
p — POINT macro instruction 

For QSJ^M ; 

CGCSl) 
(PCS!) 
CG[S],P[S1) 

Q — (5g»r macro instructions 
p „ pu»i» macro instructions 

optional modifier: 

S — SBTL macro instruction 

This information can also be supplied by the user's program or the 
DDEF macro instruction (or command). 

BLKSIZE= CBSAM or QSAM) 

specifies a decimal value for the maximum block length in bytes. 
Maximum value of BLKSIZE is 32,760. 

Specified as ; An absolute expression, maximum value 32,760. 

This information can also be supplied by the user's program, the 
DDEF macro instruction Cor command), or the data set label. 

IMSK= CBSAM or QSAM error recovery mask) 

specifies which system error handling procedures, if any, are to be 
invoked. 

Specified as ; A four-l^te hexadecimal number whose bit pattern in- 
dicates the procedures to be invoked. 

If FFfFFFFF is written, the system is to apply all optional error 
re€X>very procedures. 

If 00000000 is written, the system is to apply none of its optional 
error recovery procedures. 
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If any other four-byte hexadecimal nimiber is written^ and if an 
error occiars, the system applies its error recovery procedures to 
those errors indicated by a 1-tit in the mask. 

The first two bytes correspond to the first two bytes of the chan- 
nel status word, and the other two bytes ccrrespcnd to the first 
two sense bytes. Bit positions in each byte for specification of 
system error recovery procedures are: 

XXXXXXXX XXXXXXXX ABCDEFYY YlYl^lYY 

where a 1-bit in a given position indicates that the system is to 
handle the associated error condition: 

X = System never tests this bit to determine entry to retry 

routines 
Y = Device-dependent conditions 
1 = Command reject 
B = Intervention required 
C = Busout check 
D = Equipment Check 
E = Data Check 
F = Overrun 

Default : FFFFFFFF 

IMSK= (lOREQ error recording mask) 

specifies a four-byte hexadecimal number whose pattern indicates 
what system errors are to be recorded. 

If IMSK=FFFFFFFF (system default value) is specified, no error 
recording occurs, Although this default value invokes no error 
recording, channel control check, interface control check, and 
channel data check errors are always recorded. 

CJIDTION : Unlike most mask fields, which reguest testing for a con- 
dition when the mask tit is set to one, lORlQ tests for required 
error recording when the mask bit is set to zero. 

The first two IMSK bytes correspond to the two channel status word 
status bytes. lOREQ does not check these bytes in determining if 

error recording is required. The f^econd two IMSK bytes correspond 
to the first two bytes of sense information. The IMSK bytes have 
the following format : 

XXXXXXXX XXXXXXXX CCCCCCCC CCCCCCCC 

Where : 

• X is a status bit (not checked in determining if error record- 
ing is required) . J^ny hexadecimal number may be placed in 
these bytes. 

• C is a sense bit. When any of the first 16 sense information 

bits are set to one and the corres]^nding C bit is set to zero, 
the corresponding error is recorded. (One or more sense bits 
are set to one when a successful sense operation is performed 
after a unit check status condition has occurred,) 

Note s A 0-bit in a given position indicates that recording of the 
corresponding error is required. Error recording occurs if cne or 

more sense bits are set to zero,. Error recording should only be 
requested for equipment errors, software (that is, conroiand reject) 
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and operational (that is. Intervention required) problems should 
not be recorded. 



EXLST= CBSM4 or QSJ^) 

specifies the address of an exit list supplied by the user- See 
Appendix A for explanation of the exit list. 

Specified as ; h symbol (one to eight alphameric characters, the 
first of which must be alphabetic). 

fhis information can also be supplied by the user's program. 

NCP= (BSAM or lOREQ) 

specifies the number of consecutive READ or WRITE macro instruc- 
tions that may be issued before a CHECK macro instruction.. 

Specified as i An absolute expression, maximum value 99. 

This information can also be supplied by the user's program or the 
DDEF macro instruction Cor command). 

BUFNO= CBSAM) 

specifies the number of buffers to be assigned to the data control 
block - 

Specified, as : A binary absolute expression, maximum value 255,. 

This information can also be supplied by the user's program or the 
DDEF macro instruction (or command). 

BFALN= (BSAM) 

specifies boundary alignment of buffers. This field is ignored in 
TSS. Every buffer is automatically aligned on a dcubleword 
boundary . 

BUFIi= (BSAM) 

specifies a decimal number which is the length in bytes of each 
buffer to be obtained for a buffer pool. 

Specified as ; An absolute expression, maximum value 32,760. 

This infomation can also be supplied by the user's program or the 
DDEF macro instruction (or command). 

Default ; If not supplied by any source, the length is considered 
equal to the BLKSIEE operand. 

BFTEK= CESAM) 

specifies that simple buffering is to be employed. In simple buff- 
ering, a data set is associated with a specific group of buffers. 
A data set always uses buffers obtained from the pool assigned to 
its data control block at the time it is opened. Records can be 
moved between a buffer and an independent work area, processed 
within a btiffer, or moved from an input buffer to an output buffer. 

Specified as ; BFTEK=S 

This information can also be supplied by the user's program or the 
DDEF macro instruction (or command). 

Default ; BFTEK= S 
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BUFCB= (BSjy^) 

specifies the address of a buffer control block. 

Specified as ; Register notation (2 through 12), or a relocatable 
expression, 

This information can also be supplied by the user's program, 

EROPr= iQSim} 

When using GET/PUT macro instructions to process a sequential data 
set, an I/O error may occur. The user may specify one of three 
automatic error options to be used if there is no SYNAD routine or 
if the SYNAD routine returns control to the user's program. 

Specified as ; 

ACC — accqpt the erroneous block and continue processing 
SKP — skip the erroneous block and process the next record 
ABE -- abnormally terminate the task 

Note ; If the EROPT and SYNAD fields are not completed, the ABE 
option is assumed. 

The choice of action that can be specified depends on which proc- 
essing method (option) is specified in the OPEN macro instruction 
for the data set. The allowable combinations are as follows ; 

Action Operand OPEN Option 

ACC INPUT, RDEACK, or UPDAT 

SKP INPUT, RDBACK, or UPDAT 

ABE INPUT, OUTPUT, RDBACK, or UPDAT 

Programming Notes ; During the assembly of a source program, the DCB 
macro instruction reserves storage space in a user program in which the 
attributes of a data set being described to the system may subsequently 
be placed. This storage area is known as a data control block CDCB) and 
is created at assembly time, in line, wherever the DCB macro instruction 
appears in a user's source program. The reserved control block has a 
fixed length and consists of two contiguous parts; a common portion, in 
which all information that is access method ind^endent is to be placed, 
and an access method dependent portion. 

In addition to furnishing the storage area for holding the attributes 
describing a data set, the ECB macro instruction can also be used 
optionally, at execution time, to specify many of a data set's attri- 
butes. A user might furnish the system with such information as the 
data set organization, its record format, whether or not buffering is to 
be used during I/O operations, the type of device the data set resides 
on, and the addresses of user written routines for handling I/O errors, 
processing labels, end-of -data -set processing, and data control block 
modification routines. Any such attributes specified with a DCB macro 
instruction are automatically placed in appropriate positions in the 
reserved storage area. 

When the storage area reserved by the DCB macro instruction is filled 
with the attributes of a data set, it becomes the principal control 
block used to supply the system with information describing a particular 
data set or device. Once optional attributes have been placed in the 
control block, the DCB routine returns to the user's program. All data 
management macro instructions provided with TSS refer to this control 
block for pertinent data when they are executed. 
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DCBD — Provide Symbolic Waaes for a Data Control Block CO) 

The DCBD macro instruction generates a dammy control section (DSECT) 
that provides symbolic names for the f ielis in a data control block - 
lith proper initialization of a base register, the user may gain access 
to all fields of a data control block. 

The following conventions have been adopted: 

1. The name of the dummy control section is CBADCB. (Hn EQO is in- 
cluded in the DSECB to allow use of the alternative OS naoe 
IHADCB) . 

2. Xhe name of each field begins with the characters DCB, followed by 
the keyword operand that represents the field in the DCB macro in- 
struction. If the resulting name is longer than six characters, it 
is truncated on the right to six characters; that is, the fieli 
represented by the operani BLKSIZE= should be written DCBBLK. 
(Refer to appendix F.) 

Ihe attributes of each data control block field are defined in the 
dummy control section (DSECT) . Data control block fields containing ad- 
dresses are aligned on fullword boundaries - 

I 1 , , 

(Name | Operation J Operand f 
I ^ ^__ ^ 1 

|[syebol]|DCBD | \ 

I I I I 

Mote : A i^yrabol may be oresent in the name field but will not be 
generated. There are no operands - 

C BUT 101 : The DCBD macro instruction may be used only once in an assem- 
bly module. 

Prog r a m m i n g K o t e s : The macro instrucrion riiay appear at any point in a 
control section. The data control blocks to be accessed need not appear 
in tae saue ccntrol section as the DCBD macro instruction. 

Example : this example illustrates how a rjroaram can aain access to a 
field in a data control block through use of the DCBD macro instruction. 
ite load address (LI) instruction if used to place the address of the 
data control block in register 5. 

k USIKG statement establishes a base register for CHADCB.' The store 
operation (ST) places the value contained in register 6 into the speci- 
fied field of the data control block pointed to by register 5. DCBLRF 
is tiie field associated with logical recorl length. The user previously 

loaded regxstar 6 with the value he iesirei to be in DCBL3E . 



KYDZh DCb DDNflME=^YDCS,MAC:K?=CT (other DCB operands) 



LA 


3,HIDCB 


USI!iG 


CFiADC3,'=i 


ST 


6,DCbLRE 



DCBD 
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DDZF — Define a Data Sa t ( S) 

T'he DDEt macro instrjiction defines a iata set aiii -^escribas its 
characteristics to the system. Every ^^ata set that is referrec* to by aii 
object program ^luring execution must be deiiBea by a DDSF aacrc instruc- 
tion or coa.aan3. Each DDEF macro instruction is valil only iaring the 
session in which it is issued; thus data sets defined tor one i>essi€#n 
Biiist be reiefined at every session that involves reference -co them. 

I ^ote : The followina description aoplies to the DDEI macro instruction 
I used to deiine a ?I!^ data set on public storage. To define nonstandard 
public data sets or any private data set, refer to the detarle-1 descrip- 
tion of the DDfiF macro instruction given ir ?.ppendix «i- 

Standard form (See "Operand Strinas" in Part II, Section 1): 

I 1 1 ^ " ^ 1 

f!JaMie (Operation I Ooerand I 

I- 1 h- » 

I J[ symbol ] fDDEF | (address of operand strinaf I 
If f F 'data definition nairie[ , {VI f VP ? ¥S} ,DS'^AFF-=^naae ] » I | 

II I f ?C30lJT] I 

I , I 1 ^ I 

L-form (See "Ooerand Strings" in Part II, Section 1): 



f 1 1 ^ 

I :;iai!e [ Operation J Ci^eran^ 

I ^: . ^- ' 



I f syiLbol IDDEF | ("data def nai.e[ , (¥1 1 ?F | ¥3} , DSNAMF = dsnanie ] • ,I^F = L [ f 

f I I I PCSOUT] f 

I. i I ^ ^ -» 1 

Note : A symbol is reouired in the name field- 
S~roriu: 

I r 1 ^ ^ — ^ 1 

fNaae | Operation f Operand I 

I- 1— 1- 1 

|[ syiRbol]|DDEF |MF=(S,list) r 

I I I ^ I 



address of operand string 

specifies the address of the first operand of the operand string. 

Specified as : Register notation (2 throuah 12) or a relocatable 
expression . Note that the operand string can also be specified as 
a character string enclosed in apostrophes, as shown. 

data definition name 

specifies the symbolic data definition name associated with this 
data set definition. It -orovides the link between the data contro?_ 
block in the program and the data set definition. 

Spec ified as : A symfjol (one to eight alohameric characters, the 
first of which must be alphabetic) . '^he user is not allowed to use 
a data definition name that begins with S¥S , since system-reserved 
data definition names are prefixed with those characters. 

PCSOUT 

specifies that the proaraa. control system is being used and a data 
set is being defined for dumps. 3 ^CSOUT type of DDEF command or 



88 



Page ofGC28-2004-6 
Revised 9 May 1979 
By TNLGN20-3941 

macro instriiction is recuirei in a tdfk if the DOr.P commani is to 
be emDloyed . 

Spec if i e»l as : P C 5 O •! 

I fvi|V'P|VS] 

specifies the organization of xhe data set. 

Specified as: 



¥1 - virtual index sequential 
I V? - virtual partitioned 
¥S - virtual seauential 

I Def aulic : If neither ¥1 nor VP nor VS is specified^ the data set 
organization assigned during system aeneration is assiimeG . 

speciiies tne name of the data se-*- being defined; that is, the name 
under '^'hich the data set may be cataloged or tenDorarily referred 
to - 

Spec XL led as: The folly g^ialified naire of: a oartitioRed or non- 
partitioned data set, a luaitber of a partitioned data set, or a par- 
titiored or nonoartitionei generation of a generation data group 
(identified by an absolute aeneration naaie or relative generation 
I number) . 

Inxtiali zat ion : If this macro instruction is to be executed in a privi- 
leged laodule, the roost recently issued DCL^SS macro instruction in the 
asseikbly must have sp>ecif ie^ PRIVILEGED (see Appendix H) - Also, the 
address of a save area must be placed in register 13 before this macro 

instruction is executed. 

Prograaainq ^ot es: Before the user can employ the DUKP command in his - 
task, he must issue a PCSOUl type of DDE? macro instruction or coamand- 
Such a DBEF macro instruction or command reouires PCSOUT as the first 

operand, lollowed by the dsr.aae operand. 

I At least the definition name and DS^I'AriE operands are recuired for a 
\ previously cataloged data set. Only the data definition name is needed 
I for a new Vk^ viata set. In either case, the data set confoms to the 
current installation standards. 

The DDEF macro instruction or command causes a system entry to be es- 
tablished for the DDEF information so that allocation routines and 
access methods can refer to it. The link between this inforioation and 
the problem program •s reference to the data set (that is, the data con- 
trol block) is the data definition name. The entry containing the DDEF 
information is faaintained until the task is concluded or until, through 
tne EELSASr nacro instruction or command, the data set is released. 

The DDE? macro instruction or command may be used in conversational 
and nonconversational tasks. 

If the user's probleiL program is being executed in conversational 
mode and an undefined data definition name is referred to, prompting 
Messages for DDE? operands are issued to the user regardless of confir- 
mation option. 

The user may change the data definition narae assigned in a previous 
DDEF macro instruction or command by using a DDEF macro instruction with 
a new data definition name. The only operands used in this case are 
data definition name, DSNAfE, and disposition (OLD) . (See Appendix G.) 

Part 2: Macro Instructions 69 



PageofGC28-2004-6 
Revised 9 May 1979 
ByTNLGN20-3941 

The new data definition name is then assigned and the old data defini- 
tion name eliminated. 

Beturn Data : At completion of execution of a DDEF macro instruction, 
the low-order byte of register 15 contains one of the following hexade- 
cimal codes: 

Code S ignificanc e 

00 Successfal completion 

04 Data set name undefined 

08 Data set name not uniaue 

OC Attention interruption 

10 DSOBG in DDEF parameter list is not the same as B30RG in 

the catalog 

14 Son-existent generation name specified 

18 DSNAME not fully gualified 

1C Volume could not be mounted 

20 Space not available 

40 Data definition name not unique 

30 Other 



D EL — Delete Catalog Entry (S) 

The DEL nacro instruction deletes one or more catalog entries for a 
data set or group of data sets. Iihen a generation data group name is 
supplied, the macro instruction deletes the catalog entries for all 
generations in that group. Similarly, a partially gualified data set 
name results in catalog entries being deleted for all data sets with the 
same initial name component. 

Standard form {see "Operand Strings" in Pari: II, Section 1) : 



I — ^ T" 1 

I Name [Operation | Operand 

I h- 1 

|[ symbol ]1DEL [{address of data set nameMdata set name'} 
I I I 



L-fora (See "Operand Strings" in Part II, Section 1) : 



I 1 1 ^ 

I Name [Operation f ODeranc*- 

I- f— 1— 

I symbol |D2L | 'data set name',MF=L 
I I I 



Hote: A symbol is reguired in the name field of the L-form. 

E-f orm: 

I 1 1 1 

I Name | Operation [ Operand f 

I ^- ^ 1 

f [sya^boi jIDBL ( !«F= CE,list) f 
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address of data set name 

specifies the address of a location containing the data set naae 
(see below) - 

Specified as : Register notation (2 through 12) or a relocatable 
expression - Hote that the data set name can also be specified in 
the macro operand as a character string enclosed in apostrophes, as 

shown. 

data set name 

specifies the name of the data set whose catalog entry is to be 
deleted. 

Specified as: A character string enclosed in apostrophes. The 
data set name can be: 

• The fully gualified name of: a partitioned or nonpartitioned 
data set, or a partitioned or nonpartitioned generation of a 
generation data group (identified by absolute generation name or 
relative generation number) . 

• The partially gualified name of any type of data set, including a 
generation data group. 

If the data set is not shared, it must reside on a private volume; 
the lata set name may be the sharer's name for a data set owned by 

another user. 

Initiali zation : If this macro instruction is to be executed in a privi- 
leged module, the i»ost recently issued LCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see 'poendix r) - Mso, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

C II}IIQ:?I'S : Inis macro instruction deletes the catalog entries for data 
sets on private volumes only. H macro instruction that attempts to 
uncatalog lata sets residing in public storage is ignored and a diag- 
nostic message is produced if it is issued in conversational mode. Only 
the EEA::.E command can be used to remove such data sets from the system, 
dowever, the DEI macro instruction can be use! to delete a sharing 
descriptor from the sharer's ca+alog. 

If a user issues a D"L macro instruction against a shared data set 
for *fhich a 3DLKI0 recuest is pending, the delete reouest is not 
honored - 

?roarama.ina )iotes: ;*hen a cataloged entry for a private VAH data set is 
deleted, that lata set can only be recataloged by issuance of the EV? 
command (see Command System Us3r's Guide , r3C23-2001). Data sets on put- 
lie volUikes iiust be erased if they are to be uncatalogerl . The user 
must, therei-ore, use the FRASE command to remove those data sets from 
the system, except when he is a sharer. 

Return Data : At comoletion of execution of the DEL macro instruction, 
the low-order byte of r<=^gister 15 contains one of these hexadecimal 

codes: 

£ 9A§. ^ i an i f ica nce 

00 Successful completion 

08 Invalid return from :^EXI*?'-B 

OC Invalid data set name (innut preceded by left oarenthe- 
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sis) - -NfSXTPAR 

id No data rst name supplied after verb 

14 Return code froia CHFCXDS was nol divisible by four 

24 Data set not cataloged 

28 Data set ob a public volune 

2C Data set name is a member of a oartitioned data set 

34 SKarer aoes rot have \iiilin»itei access to data set. 



DELETS — D e lete a Loaded Module (5) 

The DELETE macro instruction indicates that a copy of a specified 
module, whicn had been placed in virtual storage, is no longer recuired. 
This specified module must have been previously acquired by the issuance 
of a LOAD aacro instruction or an explicit CALL macro instruction- Uoon 
execution of this macro ins+ruction, the soecified module, and any asso- 
ciated Modules, are deleted from the issuing task"£ virtual storaae . 



nJaae (Operation ( Onerand 
h 



t[ symbol ] I DELETE | C^?=syEibol | EPLOC=adcon group address} 



specifies the e?.ternal name of the ao.:1ule to be deleted. This ex- 
ternal naiEe must be the name of a control section, the na^e in the 
operand field of an assenbler language E2ITBY statement, or a module 
name. 

Specified as : A symbol (one tO' eiqht alohaiaeric characters, the 
firsr of which must be alphabetic) - 

E?LOC= 

specifies the a-^dress of the delete adcon group reoresentina the 
module to be deleted. 

This delete adcon grout> is generated by: 

ADCOB DEL"^TE,!^P=^xternal name 

Specified as ; Register notation (1 through 12) , or the R^ address 
of the adcon group. 

Examples : 1) If the module associated with the external name ^KKL is to 
be deleted, and the following lDCO!4 macro instruction is supplied: 

DAVE ADCON DELETE ,E^=EARL 

then the macro instruction MAX DELETE E?LOC=DAVE causes the nodule asso- 
ciated with EA3L to be deleted. 

2) The module associated with the external symbol ALPP^ is delated. 

SARF DELETE E?=ALPHA 

3) Before this DELETE macro instruction is executed, the address of the 
delete adcon group must be loaded into register 1; for example, LA 1, 
EARL. The effect of this macro instruction is then the same as in Fxam- 
ple 1. 

NAM DELETE EPLOC= (1) 
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DELIiEC — Delete a Record {R )_ 

Ihe DELESC Eacro instruction (for VISAM) deletes a specified record 
from a virtual index sequential data set. The record may be specified 
by its key or its retrieval address. 

J , J , 

IName lOoeration ^Operand f 

I 1 1 ^ , 

f[ symbol IIDELREC (deb address, {K |H} , limit I 

I I I . ^ 1 

deb address 

specifies the address of the data control block opened for the data 
set being processed . 



{K|R] 



Specified as : Register notation (1 through 12), or an HX address. 

specifies whether the record will be deleted by key or retrieval 

address . 

Spe cif ied as : 
K - record key 

R - retrieval address as obtained by the user from DCBLPA in the 
data control block 

limit 

specifies the address of a field containing either the record key 
or the retrieval address. The retrieval address must be in a four- 
byte field, beginning on a doubleword boundary. 

Specified as: Register notation (0 or 2 through 12) , or an RX 

address - 

I nitia li zation : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix K) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 



C AUTIO N : Exceptional conditions, including "invalid retrieval address" 
and "key not found", resulting from the execution of a DELPEC macro in- 
struction, cause control to be passed to the user's synchronous error 
exit (SYNAD) routine- In this case, the general registers and the ex- 
ceptional condition fields of the data control block are set as shown in 
Appendixes B and F. DELREC by retrieval address may not be used with a 
shared data set. 

P rogramming Mote : ihis macro instruction releases any page-level inter- 
locks established by other macro instructions referring to tne same DCB. 
Rules tor sharing ¥ISAK data sets are given in Appendix K. 



D ELSEG - - Delete Pi s connecte d Segmen t Gr ou p (0) 

The DELSEG macro instruction deletes a disconnected segment group. 
Ihe name and length are forgotten by the system. Space allocated on 
auxiliary storage will be returned to the system. 
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I Name f Operation | Operand 

I f f 

I [ symbol ]| DELSEG | DNIM E=di sconnected segment group name 
I t I 



DNAME= 

Specifies the eight character EBCDIC name of an existing discon- 
nected segment group. 

S pecifi ed , As ; Disconnected segment group name enclosed within apo- 
strophies, the address of DJAHE expressed as relocatable expres- 
sion, EX address or register notation. If register notation is 
used, the register specified must be the first of a set of paired 
registers containing the disconnected segment group name. 

Defaul t; None. 

B eturn Data : On return from DHLSEG, register 15 will contain a return 
code describing the success of the operation. 

het urn Codes 

00 Successful 

06 DNAME Invalia 

12 Segment group not available to user class 

40 System error 

C AUTIQ K : Any user specified DHAME beginning with SYS will be rejected 
by the system. 

E xamples : 

1. DLl DELSEG DM AKE= 'D NAME 1 • 

2. DL2 DELSEG DNA!1E=DNM 



DNK DC CLB'DNAME* 

DL3 DELSEG DNAi1E=(3) 

Execution of example 5 assumes that the disconnected segment group 
name is contained in registers 3 and 4. 



t D £Q — Dequeue Resource Access Request CR) 

f The DEQ macro instruction is used to release a resource access re- 
I ouest for a resource, or to delete all resource access requests for a 

I particular task- 

^^ J J ^ 

Name | Operation | Operand 

1 1 

symbol |DEQ |NAMB=naroe of resource 

I |[ ,¥MADDR = {Y| N} ] 

I f I y[ ,ECB=ad dress of EC3 ] 

I I I |[ pALL= {Y IN} ] [ ,TASKID = taskid ] 

f i 1 1 

f NA.-1E 

I specifies the name of the resource. 



ECB 



ALL 
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Specified a s; an EX address of aa eight byte field; the full 

field is used by the system as a name. If VMADDE=Y is specif ied, 

NaKE contains the address of the resource and is assumed to be only 

four bytes in length. 

Default: none. 

VMADDR 

specifies whether or not HAME is a virtual memory address of a 
shared resource - 

Spe cif ied as : 

I - NARE is the address of a four byte field 
N - NAME is the address of an eight byte field 

Default : N 

specifies the address of the event control block to be posted with 
the successful or unsuccessful completion of the ENQ request. 

S pecifi ed as; an BX address of a 16 byte field aligned on a 

fullword boundary. 

Def ault ; the ECB address is zero. 

specifies that all EBQ requests for the specified task, or for this 
task if taskid is not specified, are to be posted as removed- 

Spe citi ed as; the character Y 

Default : N 

TASKID 

identifies the task whose resource access requests are to be 
removed - 

Spe cif ied as: the P.X address of a half word containing the taskid. 

Default : the task issuing the DEQ is assumed. 

P roqrainroinq note s: the taskid operand is only allowed for privileged 
modules. A privileged module may purge any EKQ request, but a nonprivi- 
leged module may purge only ENQs issued by a nonprivileged routine (s) 
within the task. 

H eturn codes ; the following codes are returned in register 15: 

Code He anin q 

successful DEQ request 

4 no EKQ request found to purge 

8 parameter error on request 

Bote: for code 8 above, an error message prompt id will be in 

register 1- 



S 1& — D ele te Inter r upt Rout ine JS i_ 

The DIE macro instruction deletes control references to a previously 
specified interrupt control block. The interruption routine specified 
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in the ICB cannot service interruptions unless the ICB is respecified by 
a SIH macro instruction. 
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J j_ ^ ^ 

JName iOperation | Operand 



I [ symbol ]| DIB | (icb address , )[ ,MF= {L 1(2 r list) } ] f 

I I I . 1 

N ote : A symbol in the name field is required with KF=L. If the KF 
operand is omitted , the standard form is assumed. 

icb address 

specixies the address of an interrt?pt control block established by 
a SPECy SIECr SIEC, SSEC, STEC, or ST.EC macro instruction. This 
can be the symbol in the name field of these macro instructions. 
In the E-form of the macro inst ruction ^ this operand may refer to 
the same ICB list that is used by the SIR macro instruction. 

Specified a s; In ttie standard and L-form, as a relocatable expres- 
sion; in the standard and E-form, as register notation (2 through 
12) ; in the E-form only, as an RX address. 

I nitialization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix K) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

P rogramming N otes : A DIB macro instruction deletes an active routine 
(one currently processing or interrupted) or prevents a routine from re- 
ceiving subsequent interruptions through use of an E~form SPEC or SAEC 
macro instruction, using the MULL code for the INTTYP operand. 

R eturn Data ; On execution of DIR, the following conditions cause a re- 
turn, with a return code in register 15 and the address of the invalid 
ICB in register 1. 

Return Code C ondition 

04 ICB contains invalid DCB (for input/output and 

asynchronous ICBs only) or an invalid time 
interval or clock number was specified (for 
timer ) . 

08 No routine specified. 

OC The interruption servicing routine is active (no 

further interruptions will be presented to the 
interruption routine until it has completed its 
current servicing action) . 

10 Invalid parameter (an invalid length was speci- 

fied or a non privileged user has attempted to DIR 
a privileged routine) . 

D ISCSEG — D is conne c t Seqmen t Grou p (0) 

The DISCSEG macro instruction disconnects from an address space, a 
virtual storage segment group and assigns a unique eight character EBCD- 
IC name to the disconnected segment group. The address space previously 
occupied by the disconnected segment group is marked unassigned. 

I Not e; this macro instruction has one or more operands that can be 
I used only by a systems programmer; these operand (s) are defined and 
I specified in the System Programmer' s Guide manual. 
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L-form 



I ^ __„^ — . ^ 1 

I Name lOperation | Operand 



ISymbol fDISCSEG | [ DNAMS=, LENGTH = , BOUND= ,RNIME= , ] MF = L 

t L___ t . ^ ^ 



E-torm 



^ j ^. 

i Name j Operation | Operand 



f [ symbol JfDISCSEG | [ DNAaE=, LENGTH=, BOUND= ,RNAME= ,,ADDRESS= ^ ] 

I ! 1MF=(E,LIST) 

1 1 i__ . . . . 



S tan dara -Form 



r 1 ^ r~ ^ ^ ^ ~™ ^ ^ ^ ""■ ^ ^ — I 

I Name [ Operation f Operand I 

h 1— ^ { ^ ^ ^ 1 

|[symbol ]!DISCSEG | [ DSAME = ^ LEHGTe = , EOUMD= ,RNAME = , ADI)EESS= ^ ] | 

L i I I 

Note : all operands are keyword. 

DNAME= 

Specifies the eight character EBCDIC name to be assigned to the 
disconnected segment group. 

Specif ied as: lame enclosed within apostrophies; in E or standard 
form only, as the address of DNAME expressed as a relocatable ex- 
pression, EX address or register notation. If register notation is 
used, the register specified must be the first of a set of paired 

registers containing the disconnected segment group name* 

Default: If this operand is omitted, the system will assign a 

unique eight character EBCDIC name to. the disconnected segment 

group in the form of $$$XXXXX, where zero is less than or equal to 
XXX XX less than or equal to 9 99 99. 

C AUT IOK; Any user specified DM HE beginning with f-$$ or SYS will be 
rejected by the system,. 

LE!IGTH = 

specifies the number of contiguous virtual storage segments to be 
disconnected . 

Spe cified a s; An absolute expression; in the E or standard form 
only, the address of a halfword expressed as a relocatable expres- 
sion, EX address or register notation- It register notation is 
used, the value must be given as a binary number placed in the low 
order two bytes of the register, right adjusted. If a relocatable 
expression or HX address is used, the address pointed to must be 
two bytes long, with the length right adjusted in the field. 

Default ; If this operand is omitted, the system will assign one of 
two possible default values. They are: 

1. One virtual storage segment if BNAME is not specified. 

2. Length of HNAHE minus relative address offset • 
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BOU^D=- 

Siiecifies ¥h.ethf»r the disconnected seament groap m ust be recon- 
nectei at its 'iscorinectel address. 



Specified as : 

1. Y — disconnected sea^ent aroup must be reconnectad at itS' dis- 
connected address. 

2. N — disconnectel segF^.ent groiiD may be recornif-cted at acy a~ 
vailciLle segment aligned address. 

Der ault : L and standari forip -- l^ . 

E-form — value not chanaed in nameseq parameter list. 

speciries the reserved segment crroup from which the seqi.eBt group 
is to be disconnected. 

Specxf ied as : ^laiiie enclosed wxthin apostrophies ; in E or standard 
fora only, as the address of ES'irE expressed as a relocatable ex- 
pressxan, ftX aidress or register notation. If register notation is 
used, the register specified wust be the first of a set of paired 

registers containing the reserved segment group name. 

Derault : If this operand is omitted, the system rfill use the 
•ADDIESS" specified. 

ADLR£SS= 

sf>ecities the segment aligned relative address from which, t.he seg- 
ment group is to be disconnected- If E?iA?!E is specified, ADDRESS 
is the relative address offset fro^m the beoinnina of RMAKE- If 
PKiiHE is not specified, ADDEESS is the relative address offset from 
zero (i.e., an absolute address) - 

Sp ecif ied as: In the 1 or standard form only, the address of 
ADDRESS is expressed as a relocatable expression, RX address, or 
register notation. 

Default: Relative zero. 

leturn d ata : On return fron execution of DISCSSG, all defaulted 
operands will be filled in with systeiti assigned values. The address 
field in the nameseq parameter list ^#ill be set to an absolute address. 
Register IS will contain a return code describing the success of the 

operation . 

Retu rn Codes 

00 Successful 

04 ?B\nE invalid 

08 D^IAHE invalid 

12 Segment not available to user class 

16 Invalid address 

20 Seqment group overlap 

24 Invalid length 

28 Invalid bound option 

32 Insufficient space available 

36 User generated system reserved name 

40 System error or system limit reached 

Register 1 contains the address of the Mameseq Parameter List. 

Ii>te: The DSECT, CHAMSS covers the lameseq Parameter List. 

Programming Hotes : The return code in register 15 may be used to con- 
struct a branch table to handle the varying results from execution of 
the DISCSEG macro. 
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Upon execution of this macros a set of input flags is constructed in the 
Nameseg Parameter List. They are: 

X«80» DHIME specified 

X»40» RNAHE specified 

X»20» ADDRESS specified 

X«10» BOUND^^Y 

X«08» LENGTH specified 

Upon execution of DISCSEG, a set of output flags will be constructed 
with the above values. 

CAUTIOH : If a disconnected segment group is reconnected and BOG!JD=Y was 
specified at DISCSEG time, the total area to which the disconnected seg- 
ment group is to be attached, starting at its disconnected address, must 
be unassigned, 

L- and E-form U s e Examp le; 

DLISl* DISCSEG HF = L 

DISCSEG D!JlkME=Dl ,ADDBESS = DADD,HF= (E,DLIST) 



D1 
DADD 



DC 
DC 



CL8«MY!{A"!E» 
F«0» 



In the expansion of the L- form, a nameseg oarameter list will be 
created in the following fornat: 



DLIST 



-1-0 



.0 A.B 6. 



+ 2^4 
-I-28 



.0 0. 



Upon successful execution of E-form: 
DLIST +0 .0 \.h 6. 



+ 12 
+ 16 

+ 20 
+ 24 
+ 25 



. M . Y . D . N 
. A . H . E . b 
.0 O.a a.O 0.0 
.0 0.0 1.1 O.A B 



Where aaOOOO is a seament 
aligned address previously 
Placed at »DADD» 



DQDE CB 



, Kegove Unchec ked D2CBS From a D a ta S et_»s^ Pj-^CB Queue (B) 



The DQDECB macro instruction (for 3SAF) removes all unchecked data 
event control blocks (D'-2C5s) from a queue of uncheckel DEC3s saintaine'i 
by the system. If all of the DECEs within the cueue have not teen post- 
ed complete, the 1/0 reouests associatei! with them are purged. DQDECB 
will not proceed until all D7C5s have been posxed conipiete eixner lue to 
the purge or the fact that they have actuallv completed. 



I ?iame 



I Operation | Ope rand 



-h 



+ 



|[syiBbol]|DQDEC5 fdecb address 

i I : I 
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decb address 

specifies the address of a data event control block (DECB) associ- 
ated with the data set for which the DECB degueueing will be per- 
formed. The DECB need not currently be in the DECB queue. 

Specified as : Register notation (1 through 12) , or an EX address. 

Initialization : If this macro inptruction is to be executed in a privi- 
leged module, the most recer.tly issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M) . Also,, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

ProgramEiinQ Note s: The DQDECB macro instruction is normally used in the 
SYSAD routine when multiple READ or WRI'IE macro instructions have been 
issued without an intervening CHECK. If DQDECB is issued, all unchecked 
READ or WRITE reaiiests must be reissued. Unchecked I/O operations asso- 
ciated With the Iat>i t^at are removed from the systeai. If any of thes*^^ 
DECBs are checked after the DQDECB without an intervening HEAD or WHITE, 
the CHECK will be treated as a NOP. 

This facility is of use to users of the IHSK facilities of the DCB 
fhen they nave multiole READ or WRITE requests unchecked and want to in- 
itiate their own error retry procedures, or to the user with multiple 
unchecked READ or fcRITE requests who wants to reinitiate the sequence of 

I/O operations. 

Retu rn Da'ta : liDon retiirn from DQDECB, register conxains a count of 
the number oz unch^. ^c' :d DECBs in the queue, -and reqister 1 contc.ins a 
pointer to the list of 'unchecked DECBs. This aueue is read-only and is 
only valid until the next I/O operation is initiated on the data set. 
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EBCDfIMB — Convert System Time into EBCDIC Format fS) 

The EBCDTIME macro instruction converts time from the format in which 
it is maintained by the system into various EBCDIC formats specified by 
the user. System time can be translated into any coabination of years, 
months, days, hours, minutes, seconds, and tenths and hundredths of 
seconds by the EBCDTIME macro instruction. 

Standard form: 



I Same (Operation f Operand 
I h 



|[symboll|EBCDTIME f[ (address of format mapf»format map'}], 
I I [[time] [,L=length] 



L-fora (see "Operand Strings" in Part II, Section 1) : 



I 1 1 

(Name | Operation f Operand 



Isymbol (EBCDTIME |["foriaat map »],[ time )[ ,L=length ],MP=L 
I I I 



Mote: Jl symbol is required in the name field of the L-forn 
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E-fori 



Name 



I Operation I Operand 



-h 



[ symbol ]JEBCDTIME f[ address of format map], 

I I [time ][ ,L=length]^MP= (Enlist) 

J 1 . 



address of foraat map 

specifies the location of the format map (see below) . 

Spe cified as: legister notation (0 or 2 through 12) or a relocat- 
able expression. In the E-form, an BX address can also be asei. 
Hote that the format map can also be specified as a character str- 
ing enclosed in apostrophes, as shown. 

format map 

speciries a character string , including the soecial character 
groups that are to be converted into the time and/or date: any 
characters in the map other than the special character oroups are 
not converted. 

Spe cified as: A strina of up to 50 characters enclosed in apos- 
trophes. The desired conversion format is reauested by including 
one or more of the following groups of special characters in the 
string (the character groups can be specified in any order and can 
be separated by other characters) : 



ICHABACIEB GEOUPI 
h 



CO!f?EPTHD TO 



YYYY 

lY 

DDD 

MO 

DD 

HE 

ss 

sss 

ssss 

BUY 

DkYU 



ye 

ye 
da 
nu 
da 
ho 
mi 
se 
te 
hu 
fi 



I se 



|fi 



ar, froa 1900 to 1999 

ar, from 00 to 99 

y of year, from 00 1 to 366 

meric nonth, frop 01 to 12 

y o^ month, from 01 to 31 

urs, from 00 to 23 

nutes, froR 00 to 59 

conds, from 00 to 59 

nths of seconds, from 000 to 599 

ndredths of seconds, froE 0000 to 5999 

rst 3 characters of iionth 

rst 3 characters of day 

rst 4 characters of day 



Default: FO/DD/YY HH:rr 



time 



st-ecifies the address of a doubleword binary number of microseconds 
to be converted to tiite and/or late, as directed by the user- 
specified format map. If the time is to be converted to a date, 
March 1, 1900, is used as the base for the conversion. 

SDecified as: In tne standari and L-forms , a relocatable expres- 
sion; in the standard and S-f orm , in register notation (0 or 2 
through 12) ; Id the F-torm only, also as an Id address. 

Default : The system-maintained time (that is, the binary number of 
microseconds that have elapsed since March 1, 1900) is converted as 
directed by the format raao. 

specifies a halfword containing the length of the format i^iap (2 to 
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50 bytes) . This operand leed only be specified if the a(l<^ress of 
the foraat maD is specified in the first operani (that is, not the 
map itself, in which case the sy^^tem automatically calculates the 
length of the map) . If less than two bytes are specified when thi^ 
operand is reqii.iredr the 14-byte default map is used- l^or^ally, 
when, the length is greater than 50, the format map is truncated on 
the right; however, if- register notation is used for the length, 
an4 a length operand greater than 50 is soecified, the system 
abnormally terminates the task. 

Spe cif ied as: In all forms, a nuiiber from 2 to 50 inclusive. In 
the standard and F-forE, reaister notation (0 or 2 throuah 12) can 
also be used. 

Defa ult : If the address of the format map is specified ir. the 
first operand and the length is defaulted, the 1^-byte default map 
HO/.DD/TY rtH:MM is assumed and, in addition, a warning message is 
generated indicating that the length was not specified. 

CAUT IOH : Only upper case characters will be processed as part of a spe- 
cial character grouo. 

if the address of the forniat map is sT>ecified in the first operand, 
then the map should be reset atter each use of FBCDTIFE macro instruc- 
tion because each execution of the Eiacro would alter the map. 



P roqraiEikinq iotes 
instruction is: 



the parameter list qenerated by the EBCDTIIIE macro 



Ihegister 1 



-I Address of a half word, cor tain ing 
the length in bytes of the text 
in which the format map has been 
specified . 



r 

f 
I 

I ^ ^ ^ . 

I address of the area in which the 
[user has designated a special 
fcharacter map and in which the 
Iconverted time shall be placed ai 
Icompletion of the EBCDTIME macro 
f execution . 



Address of a binary number to le 
converted to the tirae and/or 

date. If defaulted to the system 
maintained tiie, this field is 
set to zeros. 



Word 



Worf^ 1 



Kord 2 



The length in bytes of the format E,ap is placed by the macro expan- 
sion in a half word immediately following word 2 of the parameter list. 
Similarly, the format map is placed in a field immediately following the 
length field. If tne user constructs his own parameter list, the bytes 
containing these parameters maj be placed in other locations. 

Return Data ; After successful execution of the EBCDTIHE macro instruc- 
tion, the bina ry year (YY) is returned in bits 0-15 and the binary day 
of the year (DDD) in bits 16-31 of register 15. 

If no translation is made by the EBCDTIME macro instruction, all bits 
of register 15 are set to . 
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L - and E-Form Us e: In the E-form, the optional format map operand r if 
specified,, usually points to an updated map that is to overlay the map 
defined by the L-form of the macro instruction; the updated map can be 
no longer than the original map- The L-form results in the generation 
of an in-line parameter list. 

E xamples : In EX 1 , the user has defined PBINT1 elsewhere in his program 
as: 

PRINT 1 DC CL21»THE DITE IS DD HON YY • 

He issues the macro instruction: 
EX1 EBCDTIME PPINT1,L=2 1 

On output, on the given date, PRINT1 contains: 

THE DATE IS 24 FEB 71 

In EX2, the user issues 

EX2 EBCDTIME 'THE DATE IS DD MON YY» 

In this example, the format map is defined in the operand. Following 
execution, register 1 contains an address of a two-word field; the first 
word contains the address of a field containing the length of the format 
map and the second word contains the address of the map itself. 



i E NQ — Enque ue on Re source Name (R ) 

The ENQ macro instruction is used to reguest exclusive or ahared read 
only access to a resource and to record the fact it nas access to the 
resource . 

1 ^ 1 ^ — I 

I Name |Operation | Operand 

1 ^ . 

symbol |ENQ |NAME=name of resource 

I f[ ,ECB = address of ECB ] 

I I [ ,ACCESS=tYpe of access] 

} I [ ,WAIT=aEount of time to wait] 

I f[ ,RESTYP=type of resource [ ,¥MADDR= {Y| N} ] 

^ 1— ^ L- -■ ^ 



NAr.E 



ECB 



Specifies the name of the resource. 

Specified a s: an RX address of an eight byte field; the full 

field is used by the system as a name. If ¥MADDR=y is specified, 
NAME contains the address of the resource and is assumed to be only 
four bytes in length. 

Default : none. 

specifies the address of the event control block to be posted with 
the successful or unsuccessful completion of the ENQ reguest. 

Specifi e d a s: an RX address of a 16 byte field aligned on a full- 
word boundary . 
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D efault : the ECB address is zero, provided WAIT=IM!fED; if WAIT is 
any other value, ECB cannot be defaulted. 

ACCESS 

specifies the type of access for the resource requested by the E!30 
issuer. 

Specified a s : 

HD - shared read only access; more than one user will be allowed 
access at any one time . 

WR - exclusive access requested; only the 'requesting* user will be 
allowed access. A WH request must wait for all previous users 
to DEQ before the WR reauest is allowed. 

D efault ; ED 

WAIT 

specifies the amount of time the requestor is willing to wait for 
the resource to become available for the requestor's exclusive use. 

S pecifi e d a s : 

IMHED - return without waiting if the resource is unavailale. 

No ECB is required when this operand is specified. Upon 
return, 15 will be zero if the resource was available. 

SHORT - wait for the amount of time specified as a short in the 
sysgen process. 

MEDIUM - wait for the amount of time specified as a medium in the 
sysgen process. 

LONG - wait for the amount of time specified as a long in the 
sysgen process. 

INFINITE - wait until the resource is available, or until a DEQ is 
issued . 

Default: IKFIHITE 

RESTYP 

identifies the controller of the resource. 

Specified as : 

SISTEH - system owns and controls the resource. 

USERCTL - user action controls the resource. 

USER - user owns the resource. 

Default: determined by DCLASS as follows: 

SYSTEM for PRIVILEGED DCLASS 
USER for USER DCLASS 

¥KADDR 

specifies whether or not NAME is a virtual memory address of a 
shared resource. 

Specified a s: 
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Y - NAME is the address of a four byte field 
W - NAME is the address of an eight byte field 

Default: N 

g rogramming note s: (1) Only modules vith a DCLISS PEIVILEGED may speci- 
fy RESTYP=SYSTEM • (2) The E CB address must be user read/write access 
¥hen an ENQ is issued by a non-privileged module. (3) The issuer may 
choose to be called when the ECB has been posted by marking byte 1 of 
the ECB with an X*80» and placing the V and RCON of the entry point to 
be invoked in bytes 8 through 15 of the ECB. Upon posting the ECB, a 
OLE to the entry point will be gueued. Upon entry ^ register 1 will 
point to the posted ECB. 

The ENQ macro uses registers 0, 1r 1^ # and 15 to pass parameters to 
the supervisor. Upon return, these registers will have been altered to 
contain one of the following return codes in register 15 and possibly, 
an error prompt message id in register 1: 

Code M eaning 

access gained to named resource; ECB has been posted 

4 named resource is in use, reguest gueued; 
ECB will be posted when available 

3 parameter error in reguest; register 1 contains a 
message prompt id 

The ECB will be marked as follows and should be tested by the ENO 
issuer after issuing the ENQ reguest: 

ECB - byte - X»80» wait for access 

X»7P« access granted 

X»7E* reguest purged by DBQ 

xmif wait time expired 

byte 1 - X»80' QLE to provided entry point 

bytes 2-3 - TWAIT SVC to be issued by the waiter 

bytes 4-5 - X«OaOO» reserved 

bytes 6-7 - taskid of task holding resource if 
wait time has expired 

bytes 3-11 - VCON of entry point to receive control 
when ECB is posted 

bytes 12-15 - RCOH of entry point to receive control 
when ECB is posted 



E RASE — Remove a Data Set f rom Direct Access Storage (S) 

The ERASE macro instruction releases for other use the direct access 
storage assigned to a data set. In addition, it removes the entry for a 
catalogea data set from the catalog. 

Standard form : 

I 1 1 1 

f Name I Operation | Operand I 

h 1 1 ^ » 

f [symbol ]|ERASE | {address of data set namej'data set name*} | 
I I I . 1 
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L-f orm : 
r— —J — I ^ ^ . ^ . ^ ^ , 

I Name | Operation ^ Operand I 

^^ 1 ^ ^. _ 1 

f symbol fERlSE f 'data set name»^MI=L f 

L. . I 1 . ^ . ^ . _., I 

N ote ; A symbol is required in the name field of tlie L~form. 
E~rorm : 



r ~- — ^ 1 1 ^ 

I Name fOperation | Operand 



f[symbol jfERASE fKF=(E,list) 

L_ L_ I 



address of data set name 

specifies the location of the data set name (see below) ; at that 
location, the name of the data set must be followed by a X'27». 

Specified a s: Register notation (2 through 12), or a relocatable 
expression. 

data set name 

specifies the name of any data set residing on direct access 
storage. (See "Data Set Name" in Part II, Section 1.) The data 
set name must be cataloged or must already be defined within the 
current task. 

Specifi ed as : 

• The fully qualified name of a partitioned or nonpartitio^ned data 
set, a liiember or alias of a partitioned data set, or a parti- 
tioned or nonpartitioned generation of a generation data group 

(identified by absolute generation name or relative generation 
number) • 

• The partially qualified name of any type of data set, includina a 
generation data group . 

If the data set name does not involve a member name, the direct 
access storage occupied by that data set is erased (that is, re- 
leased for other use) . The name is rewoved from the catalog if the 
data set was cataloged. 

If the data set name designates a particular member of a parti- 
tioned data set, the meaber^s name is deleted from the partitioned 
organization directory (POD) of that data set. If an alias is 
specified instead of the member name, the member name is still 
deleted from the POD. 

If the data set name is a partially qualified name or the name of a 
generation data group, all data sets (or generations) indexed under 

that name are erased and their catalog entries are removed. 

If the name of a partitioned data set is supplied without a Eember 
name, the storage for the entire partitioned data set is released, 
and its name is removed from the catalog - 

Specif ied as; The name of the data set, enclosed in apostrophes. 
(See "Data Set Name" in Part II, Section 1.) 

I nitializati on : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 

assembly mast have specified PRIVILEGED (see Appendix K) . Also, the 
address of a save area must be placed in regxster 13 before this macro 
instruction is executed. 
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C IOTION : The ERASE macro instruction cannot be used to erase data sets 
on magnetic tape; it applies to data sets on direct access storage only. 

P rograntfliinq N ote s: If a shared data set is opened by several users con- 
currently, a particular user cannot erase that data set until every oth- 
er sharer actively using that data set has issued a CLOSE macro instruc- 
tion to deactivate his use of that data set. Any effort to erase an 
actively shared open data set will be ignored and a warning message will 
be issued. Once a user is the only currently active user of a shared 
data set he may erase that data set regardless of whether he has closed 
the data set, provided he has unlimited access to the data set (set by 
an operand of the PEBMIT command) . 

E eturn Data : After execution of the EFASE macro instruction, a hexade- 
cimal code will be returned in the fourth byte of general register 15: 

Code Si an if ic an ce 

00 No error detected 
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04 Not class D or batch monitor entry 

08 Invalid return code from system module called by ERASE 

OC Invalid delimiters in data set name 

10 No data set name supplied 

14 Invalid return code from CBEKDS module 

18 Data set name not in catalog or IDT 

1C Partitioned data set not fully qualified name 

20 Member of partitioned data set not found in POD 

24 Data set not cataloged 

28 Data set on public volume 

2C Data set is member of partitioned data set 

30 Oser does not own data set in EEASE batch monitor entry 

34 Sharing /access conflicts prevent processing 

38 No catalog entry for EBASE batch monitor entry 

3C Data set name undefined (return code from DDEF) 

44 Data set not on direct access storage 

43 Volume not found 

4C Data set belongs to system - cannot be erased 

58 Data set in use 

5C Eesources exceeded, volume cannot be mounted 

E xamples : EX1 erases tne data set A .t .C . EX2 erases all data sets 
cataloged under the partially gualified name A.B. EX3 erases the data 
set whose name is stored at location NAMLOC. EX4 removes member LAUBA 
from the partitioned data set R.L.T. 1X5 generates the parameter list 
for erasing data set E.P.S., and EX6 erases K.P.S. 



EX1 


ERASE 


■A.i-».C» 


EX2 


ERASE 


•A.B» 


EX3 


ERASE 


NAMIOC 


EX4 


EBASE 


•R.L.T (LAURA) • 


EX5 


ERASE 


•M.1'.SSMF=L 


EX6 


ERASE 


KF= (E ,EX5) 



E SETL — Release Share d Data Set (R) 

Ihe ESEl'L macro instruction (for fISAM) releases a page-level READ 
interlock imposed by another macro instruction (for example, GET or 
READ) . This macro instruction does not release the write interlock 
caused by a type KX READ. See the description of the RELEX macro in- 
struction in this section. 



I 1 1 

I Name [Operation | Operand 



|[symbol ]|ESETL f deb address 

I i 1 



deb address 

specifies the address of the data control block opened for the data 
set being processed. 

Specif ied as; Register notation (1 through 12), or an RX address. 

I nitial i zation : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix K) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

CAOTION: Exceptional conditions resulting from the execution of a ESETL 
macro instruction cause control to be passed to the user's synchronous 
error exit (SYNAD) routine. In this case, the general registers and the 
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exceptional condition fields in the data control block are set as shown 

xn Appendixes B and F. 

P rogramrnxng Note : Rules for sharing fISIK data sets are given in Appen- 
dix K . 



I B XCS EG -~ Exchange S egme nt Group C O) 

The EXCSEG macro instruction performs the CONSEG and DISCSEG macro 
instructions in one operation. 

Note: this macro instruction has one or more operands that can be 
used only by a systems programmer; these operand (s) are defined and 
specified in the System Programmer's Guide manual. 

L -f orm 

^.. J J ^ J 

I Name | Operation f Operand I 

|_ 1 1 1 

I Symbol lEXCSEG | [ DNA«E = ,. LENGTH=, BOUND= rP-NAM£= , ] MF = L | 

L^ 1 I I 

E -form 

J . J ^ 1 ^ J 

I Name | Operaiiion f Operand I 

I ^ 1 . 1 ^ 1 

I [symbol ]|EXCSEG | [ DNAME=, LENGTH=, BOUND= ,ENAHE= , ADDBESS= , ] f 

f f |MF=(E,LI3r) I 

I . — I i . I 

S tandard -For m 

J J , 1 ^ __«^ 

I Name f Operation f Operand I 

f- h- 1 — f 

f [symbol IfEXCSEG |DNAME=[ , LEN GTH= pBOUIID = ,H!IAME=^ ADDRESS = , ] [ 

I 1 1 I 

M ote : all operands are keyword. 

DNAHE= 

specifies the eight character EBCDIC name of an existing discon- 
nected segment group. This name will be assigned to the segment 
group being disconnected. 

Spe cified a s; Name enclosed within apostrophies ; in E or standard 
form only^ as the address of DNAKE expressed as a relocatable ex- 
pression, HX address or register notation. If register notation is 
used, the register specified must be the first of a set of paired 
registers containing the disconnected segment group name. 

Default : none 

C AUTIO N: Any user specified DNAME beginning with SYS will be rejected 
by the system - 

LENGTH= 

specifies the number of contiguous virtual storage segments to be 

disconnected. 

S pecified a s: An absolute expression; in the E or standard form 
only, the address of a half word expressed as a relocatable expres- 
sion, RX address or register notation. If register notation is 
used, the value must be given as a binary number placed in the low 
order two bytes of the register, right adjusted. If a relocatable 
expression or RX address is used, the address pointed to must be 
two bytes long, with the length right adjusted in the field. 
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Default : If this operand is omitted, the system vill assign one of 
two possible default values. They are: 

1. One virtual storage seoment if RHAME is not specified. 

2. Length of RNAilS minus relative address offset. 

30UIID = 

specifies whether the disconnected segment group must be recon- 
nected at its disconnected address. 

Specified a s : 

1. Y -~ disconnected segment group must be reconnected at its dis- 
connected address. 

2. N -- disconnected segment group may be reconnected at any a- 
vailable segment aligned address.. 

Default: L and standard form -- N. 

E-form — value not changed in nameseg parameter list. 

HNIKE= 

specifies the reserved segment group from which the segment groups 
are exchanged. 

Specified a s: Name enclosed within apostrophies; in E or standard 
form only, as the address of RNAHE expressed as a relocatable ex- 
pression, RX address or register notation. If register notation is 
used, the register specified must be the first of a set of paired 
registers containing the reserved segment group name. 

Default ; If this operand is omitted, the system will use the 
•ADDRESS • specified . 

ADDRESS= 

specifies the segment aligned relative address from which the seg- 
ment group is to be disconnected. If RNAKE is specified, ADDRESS 
is the relative address offset from the beginning of RNAME. If 
RHAME is not specified, ADDRESS is the relative address offset from 
zero (i.e., an absolute address). 

S pecifi ed as: In the E or standard form only, the address of 
ADDRESS is expressed as a relocatable expression, RX address, or 
register notation. 

Default : Relative zero. 

R eturn data : On return from execution of EXCSEG, all defaulted operands 
will be filled in with system assigned values. The address field in the 
nameseg parameter list will be set to an absolute address- Register 15 
will contain a return code describing the success of the operation. 

Return Codes 

00 Successful 

04 RNAME invalid 

08 DNAME invalid 

12 Segment not available to user class 

16 Invalid address 

20 Segment group overlap 

24 Invalid length 

28 Invalid bound option 

32 Insufficient space available 

36 User generated system reserved name 

40 System error or system limit reached 

Register 1 contains the address of the klameseg Parameter List. 
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I N ote ; The DSECT, CHANSG covers the Nameseg Parameter List. 

P rogramming Note s: The return code in register 15 may be used to con- 
struct a branch table to handle the varying results from execution of 

the EXCSEG macro- 

Upon execution of this macro, a set of input flags is constructed in the 
Nameseg Parameter List. They are: 

X«60« DNAME specified 

X«40» BNAME specified 

X«20 • address" specified 

X*10» BOUliD=Y 

X»08« LENGTH specified 

X»04» RELEAS=Y specified (for system programmers only) 

I Upon execution of EXCSEG, a set of output flags will be constructed with 
the above values. 



E XIT — Norm al Prog ram End f R) 

fhe EXIT macro instruction terminates program execution and switches 
the task to command mode. The words "EXIT, RELEASE ALL UHNEEDED 
DE¥ICES*% followed by the message specified in the macro instruction are 
written on SYSOUT. If the NOBSG operand is specified, neither the sys- 
teiL message nor the user -specified message is written. 

^ j , ^ ^ 1 

I Name | Operation | Operand | 

h 1 1 — 1 

f [ symbol ]| EXIT I[ {address of message f » message text*}] [,HOMSG] | 

address or message 

specifies the location in storage that contains the message to be 
issued* The first byte of the message must contain the length of 
the message (in bytes) ► 

Specified a s; Register notation (1 through 12), or an EX address* 

message text 

specifies the actual text of the optional message to be issued. 

Specified a s: The message itself, enclosed in apostrophes. 

HOWSG 

specifies that no messages are to be printed on SYSOUT when the 
exit is taken. 

Specif i ed a s : N as G . 

Default : The messages are printed- 

I nitializati on : This macro instruction cannot be assembled in a privi- 
leged module unless the most recently issued DCLASS macro instruction in 

the assembly specified OSEF (see Appendix K) , or the DCLASS option is 
USEE by default. 

P rogramming Notes; If EXIT is issued in a conversational task, the mes- 
sage is written on the user's terminal and the next command is taken 
from the terminal. If issued by a nonconversational task, the message 
is written on the SYSOUT data set and the next command is taken from the 

SYSIN data set. 

The EXIT macro instruction returns control to the Co^mmand Analyzer. 
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E xamples : In EX 1 , the user supplies the message text as a character 
string. In EX2, the message text is given at location MSGTEXT . In EX3 
and EX4 , no messages vill be printed on SYSOUT. 

EX1 EXIT •COMPLETED ABDUOUS« 

EX2 EXIT MSGTEXT 

EX3 EXIT ,NOHSG 

EX4 EXIT "PRINT THIS • ,NOMSG 



Part 2: Kacro Instructions 108.3 



PageofGC28-2004-6 
Revised 9 May 1979 
By TNL GN20-3941 



F EQY — Force End of folmia e (R) 



The FEO¥ macro instruction (for BSAK) directs TSS to advance to the 
next volume of a data set before the end of the current voluitte is 
reached. This macro instruction is applicable to BSAM data sets mounted 
on magnetic tape or on direct access devices- 



f Name 
I 



~i 1 

^Operation JOperand 



J[ symbol IJFEOV fdcb address 

I I I 



deb address 

specifies the address of the data control block opened for the data 
set being processed. 

Specified as : Register notation (1 through 12) , or an RX address. 

Initialization : If this macro instruction is to be executed in a privi- 
leged module^ the most recently issued DCLASS aacro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M) . Also^ the 
address of a save area must be placed in reaister 15 before this macro 
instruction is executed. 



CIUTIOH; 



The followinq errors cause the results indicated: 



Errors 



Result 



I The deb aliress oi^erand specifies the address of a 
I data control block that is not open. 

r 

I the deb address operand specifies tne address of an 

linvalxd daxa control block. 

I 

jThe data set is not being processed by BSAM (magnetic 

I tape or direct access devices) - 

I 

I Hot all BSA^i P^AD or WRITE iBstructicns on the data 
I sets have been checked. 



I No action 

(Task terminated! 

Task terminated I 

[Task teminatedl 



E xampl e : In the following example, the control orograia is directed to 
advance ro the next volume of the data set associated with the data con- 
trol block HEPOF.l. 



EX1 



^ISOV 



REPORT 



fl^D — iJDd a Member of a Partitioned Data Set (S) 

Ihe FIKD Biacro instruction (for ?PAM) searches a partitioned organi- 
zation directory to locate a directory entry for a member and optionally 
places the user's data associated with the member into the specified ar- 
ea. The ikember is opened and positioned for processing. 

Standard forii: 

I f 1 1 

[Name f Operation f Operand f 



+ 



_| ^ 

I icb address ,name[ , area, lenath ] 



|[ sysbol j|f IND 
I I 
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L- and E-forE: 

, J 1 

IH.aae | Operation | ODerand 



|[ symbol]|FIND f [ deb address ],[ name ] [ 

f I »[, area, length 3, RF= {LI (Enlist) } f 

I 1 L_ . I 

^ote : A symbol is recaired in the name field with the L-forE. If ei- 
ther of "the first two oTierands is omitted from the L-form^ it must be 
suppliei with the F-fom. 

deb address 

specifies the aidress of the data control block ooened for the data 
ser being processed - 

Specified as : A relocatable expression; in the standard and E- 
forms, as register notation (2 through 12); in the E-form only, 
also as an EX address. 

naiie 

specifies the location of the eight-character menber name, or 
alias, that is to be used to locate the member. 

Spe cifi ed as: Sape as the first operand. 

area 

specifies the location of the user data area into which the user's 
data associated with the member is to be placed. If the area 
operand is specified, the length operand must also be specified. 

Spec ifi ed as: Saiae as the first operand - 

length 

specifies the number of bytes in the area provided for reading in 

the user data. 

Specified a s: In the standard and E-forms, as an absolute expres- 
sion or in register notation {? through 12) ; in the L-form, as an 
absolute expression only. 

In itializatio n: If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS iLacro instruction in the 
assembly must have specif iec^ PBIVILEGED (see Ippendix E) . Also, the 
address of a save area aust be placed in register 13 before this nacro 
instruction is executed. 

CAUilQW : The FIND macro instruction causes an abnormal termination if 
any conditions are discovered that make continuation impossible. 

P roqra mEi nq H otes: If a DCE is opened with a DSOHG of either VIP or 
VSP, only members with a matching DSOPG are processed by FIND. If a 
mismatch is detected by FIND, a X"OC" code is returned to the user indi- 
cating the mismatch- (The user can still process mixed member V^hE data 
sets by specifying DSOPG=VP in the DCB.) 

If a DCB is opened with a DSORG of either VIP or VSP, only members 
with a matching DSOPG are processed by FIHD. If a mismatch is detected 
by FIND, a X'OC code is returned to the user indicating the mismatch. 
(The user can still process mixed member VPAK data sets by specifying 
DSOEG=VP in the DCB.) 
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If the length specified is less than the' actual length of the user 
data in the ?0D^ both the area an^ length operands are ignored and gen- 
eral register 15 contains an appropriate error code (X'10») . Hules for 

sharing ¥?&il data sets are given in Appendix K. 

For shared VPAK data sets, the following interlocks are set by a FIHD 

macro instruction: 

1. YISAH members are: 

• write interlocked when opened for OOT^OT. 

• read interlocked when opened with .any other option. 

2. VSAl Eembers are: 

• read interlocked when ooened for INPDT« 

• write interlocked when ooened with any other option. 

Retarn Data : After execution of the FIJD F-acro instruction , reaister 
contains the length of the user data in the ?0'D. Register 1 points to 
the parameter list shown below., 

I^AEAriETER LIST 



-T 



I Register 1 | fDcb address |Word 

t 1 , ^ ^ 1 

niember name fiord 1 

I 4 

|*Pointer to the user data area [lord 2 

f- ^ ^ ^ » 

I*Pointer to the lenath, in bytes, of the fWord 3 
I user data area I 

I ^ . ^ . — _- 1 

*These are zero if not supplied in the 
macro instruction. 

The length, in bytes, of the user data area is placed, by rhe macro 
expansion, in a word imaediately followincr word 3 of the parameter list. 
However, if the user constructs his own oarameter list, the word con- 
taining this length may be placed in some other location. 

After execution of the FIND macro instruction, bits 24 through 31 of 
register 15 contain one of the following hexadecimal codes, indicating 
the status of the operation. The user should take appropriate action 
depending on the code returned. 



Part 2: Kacro Instructions 111 



PageofGC28-2004-6 
Revised 9 May 1 979 
ByTNLGN20-3941 



Code 



Def iBition 



00 I Successful completion of FIND. 

04 I Member or alias was not located by FIND. 

08 \ The data control block indicated in the macro instruction is 
in use for creating a member. Execution of a STOW must be 
complete before this FIMD can be executed. 

OC I DSORG of member to be located does not match DSORG in DCB 

(this return code can only occur if the DSORG specified in the| 
DCB is VIP or FSP) . 

10 I The length specified in the macro instruction is not large 
enough to contain user data. 

t4 I The member to be located is already open for this data control | 
blocks due to a previous FIND. 



If the FIND macro instruction is used for a library search^ the area 
operand must specify a length of 2U bytes. After execution of the lacro 
instruction^ the six words of the area contain: 



Mord 1 IRelative page number of the proaram module dictionary (PHD) 



Word 2 (Length of the proaram module dictionary 



Word 3 I Relative page number of the text 



Word 4 I Length of the text 



Word 5 fRelative page number of the internal symbol dictionary (ISD) 
I- 



word 6 (Lenqth of the internal symbol dictionary 



I FIHDDS — Locate JFCB Corresponding to Data Set game ( S) 

I The FI]:!DDS macro instrucxion is used to obtain the location of the 

I JFCB corresponding to a given data set name. If the data set name Is 

I not in the task data definition table (TDT) , bur is in the catalog, the 

I user can request that a JFCB be created - 

f Standard form: 

I 1 1 — ' ' 1 

I fUame | Operation f Operand I 

( f 1 



h 



I |[ symbol ]|FI^DDS | data set name , byte, area 



I L-form; 



I I Name | Operation | Operand 



-I- 



-h 



I Isymbol IFINDDS [[data set name ],[ byre ],[ area ],Mf=L 

I I I ^ , , 

I Note : A syjBbol is required in the name field. ? ny operands oaitted 
I must be specified in the E-form- 
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E-f or»: 

J 1 J ^ . — I 

JMarne lOoeration lOperand \ 

I 1 1 ^ 1 



area 



|[ symbol JfFINDDS |[aata set name ],[ byte], [ area ],MF= (Enlist) f 

I 1 1 ^ I 

Note : If E-form operands are specified, they will overlay those speci- 
fied in the L-form. The list operand must specify the symbol in the 
name field of the I-fora; or the symbol (a relocatable expression) may 
be loaded into register 1 and the list operand specified as (1) - 

data set name 

specifies the address of a fully gualifiei data set name. The data 
set name located at the specified address must be padded on the 
right with blanks if less than thirty-five characters. 

Specified as ; In the standard and L-form, as a relocatable expres- 
sion; in the standard and E-form, in register notation (2 through 
12); in the E-form only, also as an RX address. If register nota- 
tion is used, the address must first be loaded into the specified 
register. 

byte 

specifies the address of a byte that the user has set to zero if he 
wants a JFCB created for a cataloged data set, or to non-zero if he 
does not want a JFCB created. 

Sp e cified as: In the standard and L-form, as a relocatable expres- 
sion; in the standard and E-form, in register notation (2 through 
12) ; in the E-form only, also as an EX address. If register nota- 
tion is used, the address must first be loaded into the specified 

register. 

specifies the address of a word in which the pointer to the JFCB is 

to be placed. 

Specified as: In the standard and L-form, as a relocatable expres- 
sion; in the standard and E-form, in register notation (2 through 
12); in the E-form only, also as an II address. If register nota- 
tion is used, the address must first be loaded into the specified 
register. 

Initialization: If this macro instruction is to be executed in a privi- 
legeu. module, the most recently issued DCLISS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M) . Also, the 
address of a save area must be placed in register 13 before this macro 
instrucrion is executed. 

Return Data : A hexadecimal code is returned in register 15: 

Code Me aning 

00 JFCB found or created as recruested. 

Ok No JFCB found; no reoaest to create one. 

Ob Uo JFCB found; recruesx to create one, but DDEF could not find 
lata set name in catalog - 

DC lo JFCB found; DDEF could not create one because soace 
unavailable. 

10 Data set name invalid; CHEKDS return code indicates dsname 

invalid form. 

Part ?: Hacro Instructions 112.1 



PageofGC28-2004-6 
Added 9 May 1979 
By TNL GN20-3941 

14 No JFC5 found; DDEF return coie indicates volume could not be 
mounted . 

F Ili DJFCB — Locate J -gCB 'and Ensure ¥olugte Mountin g (S) 

The FINDJFCB macro instruction is used to locate the JFCB for a qiven 

data dexinition name and ^ optionally, to ensure that the volumes speci- 
fied in that j?CE are mounte'l- 

Standard form: 

I J J ^ ^ 1 

fName f Operation f O-peranc I 

I -I 1— . 1 

I [ symbol ]i±"INDJFCB | dinaroe , byte , area I 

I I I ^ I 

L-f orm : 

I — T— 1 ^ 1 

f Name fOperation ^Operand I 

|. ^ 1 1 

Isymbol IFI'IDJFCB | [ ddr^ame 1,[ by te ],[ area 1 , MF=L | 

i I I ^ ^ 1 

li£i.§.- ^ symtol is required in the name field. Any operands omitted 
must be specified in the E-form. 

E-f orm: 

I Name | Operation | Operand I 

I 4_: ^ _ , 

I [ symbol ] I FIND JFCB I [ ddname ],[ byte ],[ area ],MF= (Enlist) f 

Note : If E-forii operands are specified, they will overlay those speci- 
fied in the L-f orm. The list operand aust specify the symbol in the 
name field of the L-forni; or the symbol (a relocatable expression) may 
be loaded into register 1 and the list operand specified as (1)- 

ddname 

specifies the address of an 8-byte field containing the data defi- 
nition name- If the data definition name in the field has fewer 
than 3 characters, it must be left-aligned with trailina blanks. 

Sp ecified a s: In the standard' and L-form, as a relocatable exores- 
sion; in the standard and 2-f orm , in reaister notation (2 through 
12) ; in the E-form only, also as an RX address- If register nota- 
tion is used, the address must first be loaded into the specified 
register. 

byte 

specifies the address of a 1-bvte field containinp a code indicat- 
ing the processing action that is to be taken, whether the JFCB is 
found or cannot be found. The codes and their meanings are: 

Code f^ea ninq 

00 If JFCB is found, mount volumes, and return with appropri- 
ate data; if not found, issue diagnostics and an ^BEND for 
the task. 

01 If JFCB is found, mount volumes; whether JFCB is found or 
not, return to issuing program with appropriate data. 

02 If JFCB is foundf do not mount volumes; whether JFCB is 
found or not, return to the issuing program with appropri- 
ate return data. 

Specified as : In the standard and L-f orm, as a relocatable expres- 
sion; in the standard and E-form, in register notation (2 through 
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12) ; in the E-form only, also as an SX address. If register nota- 
tion is used, the a^^dress nnst first be loaded into the specified 

register- 
area 

si>ecifies the address of a 4~byte field in which the address of the 
JiCt> is to be placed. 

Specified as : In the standard and L-form^ as a relocatable expres- 
sion; in the standard and F-forHr in register notation (2 through 
12) ; in the E-form only, also as an RI address. If register nota* 

tion is used, the address must first be loaded into the specified 

register. 

I n i t ia li 2 at ion : If this macro instruction is to be executed in a privi- 
leged module, the most receittly issued DCLiSS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M) . Also, the 
address of a save area siust be placed in register 13 before this macro 
instruction is executed - 

Execution : The task data definition table (TDT) is searched for a JFCB 
with the specified name. If the JFCB is not found, the co^nversational ' 
user is asked whether he wants to define a data definition name. If he 
indicates yes, DDEF is called to build the JFCB. If he indicates no, or 
if the task is nonco^nversational, the action taken depends on the proc- 
essing option code. When the JFCB is found, or created, a check is made 
to see if the proper volumes are mountei (unless the processing option 
of 2 was specified) . When mounted, a pointer to the JFCB is set in the 
output area, and control is returned to the issuing program. 

Return Data : The output area is set to zeros if the JFCB is not found 
(except for processing option 0) and to the address of the JPCB if it is 

found . 

FREEBOF -- Return a Buffer to a P ool (R) 

Tne FFEEBOF macro instruction (for BSAr) returns a buffer (previously 
obtained by a GITBUF macro instruction) to a buffer pool, so that it 
will be freed and can be obtained again by GETBOF. It is not necessary 
to free all buffers prior to issuing the CLOSF macro instruction. 



I " 1 ^ ^ 1 ^ ^ 

JMame fOperation f Operand 

I 1 ,_ ^ 

f[ symbol ]f?HEEBUF fdcb address , buff er address 



deb address 

specifies the address of the data control block opened for the data 
set being processed. 

Specified as ; Register notation (1 through 12) , or an RX address. 

buffer address 

specifies the register that contains the address of the buffer be- 
ing returned to the pool- 
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specified a s; In absolute expression, 2 through 12. 

Initialization ; If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix H) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

CADI' ION ; Error conditions that result in termination of the task are: 

1. An invalid data control block is specified. 

2. The buffer pocl address is not in the data control block (GFTBU? 
was not invoked before FREEBUF) . 

3. The buffer address specified by the user does not belong to the 
buffer pool. 

4. The buffer specified by the user is not in use (GETBUF was not used 
to obtain the buffer) . 

ProcrramHiinq Ijot es : To release a buffer by IBEEBUF, a buffer pool must 
have been assigned to the data control block r and the specified buffer 
must have been obtained by the GETBUF macro instruction. 

Ex ampl e: See the example in the GETBUF macro instruction description. 



FREEflAIN — Rel e ase Alloca t ed Vir t ual Sto rage [Rl 

The FREER AIM macro instruction releases a virtual storage area previ- 
ously allocated by a G^±MAI^^ macro instruction- This virtual storage 
area can be released by units of pages or 8-byte multiples. 

I 1 1 ^ 1 

[Name f Operation | Operand f 

I ^ 1 , 

J[symbol]|FREEHAIN ({PAGE [ , VAS ] I R] ,LV=length, A = addre£S | 
I I I . 1 

PAGE 

specifies that a number of pages of virtual storage are to be 
released - 

Specified a s : P AG E 

specifies the release of an area of virtual storage obtained 
through a PAGE,VAR GETFAI''! macro instruction. This operand is only 
specified if PAGE is specified. 



?AR 



LV 



Spec ified a s: VAR 

specifies that a number of bytes of virtual storage is to be re- 
leased (LV must specify a multiple of B bytes) . 

Specified as : R 

specifies the length, in pages or in bytes (as specified by PftQE or 
R) , of the virtual storage area to be released. The LV= operand 
must be written as in the corresponding GETHAI:! macro instruction. 
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Specified as: An absolute expression, or register notation (0 or 2 
through 12) • If register notation is used, the length must be 
given as a binary number placed in the low-order three bytes of the 
register specified, right adjusted. The high-order byte of the re- 
gister must be . 

A 

specifies the address of a f ullword containing the address of the 
virtual storage area to be released. 

Spec ified as: Register notation {1 through 12), or an BX address - 

It register notation is used, the address of the virtual storage 
area (not the address of a f ullword containing the virtual storage 
area address) must be loaded into the register before execution of 
this macro insi:ruction . If bytes are specified, the address of the 
virtual storage area must be on a doubleword boundary (or an error 
code of J*0&* is returne'^. in register 15). 

Initialization : If this macro instruction is to be executed in a privi- 
leaad module, the most recently issued BCL ASS macro instruction in the 
assembly must have specified PRIVILEGEB (see Appendix K) . Also, except 
when E is specified as the first operand, the address of a save area 
must be placed in register 13 before this macro instruction is executed. 

During execution of the FREERAIM macro instruction, the task issuing 
the FbEEMAIH macro instruction is abnormally terminated if : 

• the area to be released is privileged or contains privileged areas, 
or 

♦ the area to be released was not allocated by a GFTJ1AIH. 

Betu rn Data : If FPESrillbf is unable to locate the paae or doubleword 
boundary containing the virtual storage to be released, or if any of the 

virtual storage has ' never been assigned or has already been released, a 
return code of X»0^" is placed in register 15. If a doubleword boundary 

is not specified, X'03' is returned in register 15. 

Examples : 

EX1 requests the release of a 16-page virtual storage area whose 
address is in register 1 . EX2 reouests the release of an area whose 
address is in the fullword at ^DDI and whose length, in pages, is in re- 
gister 0. EX3 requests the release of an area whose length is two pages 
more than the value specified during system generation (see the descrip- 
tion of the GETf AI^ macro instruction) , and whose address is in the' ful- 
lword at ADD2. EX4 recruests the release of 200 bytes of virtual storage 
whose address is in the fullwori at ADD3. 

2X1 FPEEKAIJ ^AG-E,IV=16,A= (1) 

EI2 FPEEMAIH ? AGE ,L¥= (0 ) , A= ADDl 

EX 3 FH REMAIN 2 AGE , VAS, L¥ = 2 , A^ADDz 

EX4 FF.EEFAINI R ,1V = 200 , A =ADr 3 

t5£EI-QQL — F ree a buffer P oo l £R 1 

The FFEE.?OOL macro instruction (for 5SAM) releases an area that had 
previously been assigne"^ as a buffer pool to a specified data control 
block. The area must have Deen acquired through either the execution of 
a GEIPOOL Eiacro instruction or by the buffer ootion described in the DCB 
macro instruction; that is, when the DCB macro instruction was written, 
BUFiO=- and BOFI= were included. FFEEPOOL need not be issued if a CIOSE 
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macro instructioB is issued for the data control block to whick the 
buffer pool is assigned. 

I — ' 1 1 ^ 1 

fNaiie fOperatioK I Operand \ 



|[ symbol jfFaEEPOOL |dcb address 



L 



deb address 

specifies the address of the data control block to which the buffer 
pool was assigned. 

Specified,, as : Begister notation (1 through 12) , or an Ry. address. 

CA DTIOU : If the deb address operand does no^ specify rhe ad,dress of a 
valid data control block, the task is terminated. 

Initial izat ion : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEf^ED (see Hpi^endix f) . Ilso, the 
address of a save area ffiust be i>lacel in register 13 before this macro 
instruction is executed. 

P rogra mmi ng Not es: If the associated data set is orocessed Ly r^ieans of 
3SAM, FREEPOOL may be issued as soon as the buffers are no longer 
reguired . 

Examples : ilXI releases the buffer area assigned to the data control 
block whose address is OUTPUT. EX2 releases the buffer area assigned to 
the data control block whose address is in register 1. 

EX1 FEEEPOOL OOTPUT 
EX2 FREEPOOL (1) 

See also tn.e example in the GET3UF macro instruction description. 

GATRD — Get Record froa STSIN (S ) 

The GATED macro instruction reads a record from the user's SYSIl and 
places it in a specified area. 

Standard form: 



I Name fOoeration | Operand 

I- \— h 



f[syiabol]JGATRD finput area, length[ , SIC ] 

I I ^ — I ^ ^ 



L- and E-form: 



I 1 1 ^ — ' 

fName I Operation f Operand 

\ 1 \ 

|[symbollfGATRD r[input area! , length ][ ,SICl,WF={LI (Enlist) } 



Hote: A symbol is required in the name field with MF=L. Either of the 
first two operands that is omitted from the L-form must be supplied with 
the E-form. The operands specified with the E-form will overlay those 
specified with the L-form. If the MP operand is omitted, the standard 
foria is assumed. 

input area 

specifies the address of the area into which the input record is to 
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be Diaced- The user must 'iefine the length, of this area by the 

length operand. 

Spec iried a s: In the standard aR3 L-form, a relocatable expres- 
sioB ; in the standard and S-forM^ register notation (? through 12); 
in the E-form only,, an RX a d dress - 

length 

specifies the address of a full¥or5 containing the length of the 
expected inpat record; the aaxiiiari length of the line depends upon 
the input source: 

¥AM data set 123 characters 

1050 13D characters 

274 1 133 characters 

Kodel 33 and 35 KSHi 72 characters 

Note: This ooerand must be specified in either the L-forn or the 
E-form of the macro instruction- On return^ the actual record 

lengtu is stored at the same address. 

Spec ified as: Reaister notation (2 throoah 12), or a relocatable 
expression . 

SIC 

indicates whether characters within SYSI^ representing control 
functions (specified as such in the Character Translation Table, 
CIT) are to be reqarded as input characters by the GATED nacro in- 
struction. If SIC is specified, all characters in the CTT (located 
in the task profile) are translated to internal code and trans- 
mitted to storaae regardless of the functional code assigned to it 
in the CTT . 

Sp ecifie d as : S IC 

Default : Omission of this operand reouests the standard mode in 
which only characters assigned the translation code (00) in the CTT 
are translated and transferred to storage, while characters assign- 
ed to other functional codes are not transferred to storage. •r'hus, 
in the standard mode, characters within a line of SYSIN that are 
assigned unigue functional codes in the Character Translation Ta- 
ble, such as the backspace or cancel control functions, are not 
read into storage as part of the SYSIH input line. 

Initializ ation : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PBIVILEGED (see Appendix S) . Also, the 
address of a save area aust be placed in register 13 before this macro 
instruction is executed . 

C&PTIOB : Records whose length is no longer than one line (from the ter- 
minal keyboard) , or one card image (from the terminal card reader) are 
read by one GATRD macro instruction. Records longer than one line or 
card image are truncated if continuation of the record is not indicated 
(See the description of the CONT operand of the MCAST macro 



^Terminals which are eguivalent to those explicitly supported may also 
function satisf actorly . The customer is responsible for establishing 
eguivalency. IBM assumes no responsibility for the impact that any 
changes to the IBF-supplied products or programs may have on such 

terminals. 
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f instruction.) If continuation is indicated, succeeding GATRB aacro in- 
I structions can be used to read the remainder of the record. 

I Programainq lo te: GATED cannot be used to recover a record that was 
read by an earlier GATED. 

If the SIC operand is specified, both input characters and control 
characters must be included in the length count specified via the length 
operand of the GATED macro instruction. 

In the standard mode, a character is transmitted to the nessage area 
only if it satisfies the following four conditions: 

1. It is assigned the trai^slation code (00) in the Character Transla- 
tion Table (see Command System User's Guide for a^^ditioDal informa- 
tion pertaining to the CTT) . 

2- It is not deleted by the action of any characters that are assigned 
the backspace or cancel functions. The user is cautioned that 
there may be extraneous characters beyond the text returned in the 
input area. This arises from the fact that the backspace function 
on the end of the line causes the message length to be adjusted 
only so that terminal characters removed by a backspace ©ay show in 
the unused portion the inout area. 

3. It appears on a record to the left of all characters assianed the 
end-of-message function. 

4. Space is available for it in the area specified by the input area 
operand. 

If a GATED is executed in a loop and the user wishes to have the sane 
value for the expected record length each time, he wast reinitialize the 
length in field each ti^e GATED is to be executed. 

Note: Only that portion of the recori froii the pointer on is available 
to the user. See Appendix 1 of A ssembler Prograntin er '£ Guide for more 
inf ormarion on record formats. 

Retu rn Data : On return from G»TBD, register 15 contains two bytes of 
coded information (hexadecimal) in bits 16-31, as shown in Fiaure 10. 

Example: A 120-character record (that is, 120 characters assigned the 
translatior function within the CTT) is to be fetchec^ from SYSI^ and 
placed in the area READIN: 

EXl GATED HEADIIJ,ILE^GTK 

In this example, the user has defined the length elsewhere Ie the 
program : 

ILB'JGTH DC F«120« 

Note that the absence of the SIC parameter defaults to the standard 
mode, in which only those characters assigned the 00 translation code in 
the CTT are to be translate 1 by the standard Character Translation ^'able 
and transmitted to the input area. 
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f Bits 16-23 Code 



Significance 



Input record contains no continuation code; record 
is therefore complete. 

Input record contains a continuation code. Issue a 
GATRD to get next portion of record. 

Record was truncated because it exceeded maximum 
length specified by the user. 



Bits 24-31 Code 





3 

10 



SYSII is non-conversational 

Attention interruption occurred; record, if any, is 
unpredictable . 

SYSIN is froM terminal keyboard. 



Figure 10- Return codes from read-only and write-with-read GATE macro 
instructions 



GATW R — Write lecor d o n SY SQI3T (S) 

The GAfWR macro instruction writes a message on the user's SYSOOT 

froi* an area in storage. 

Standard fori.: 

J J 1 ^ — ^ . ^ 

IHaiie I Operation I Operanf 

I —i — ■ -¥~~- ■ ^ ■ — -— ■— _ 

|[ symbol ]lGAT\iH ( message ,length[ ,SIC] 



L- and E-form: 



I Hare 

I 4 

{[symbol JIGATSR 



lOperation [ Operand 



f[ message ],[ length ][ rSIC][ ,MF=CL| fE,list)} ] 



I 



Mote : A syabol is require. I in the name field with MF=L. Either of the 
first two operands that is omitted from th3 I-form must be supplied with 
tiie E-fora- The operands specified with the E-form will overlay those 

specified in the L-f orm . If the HF operand is omitted, the standard 
form is assumed . 

laessage 

specifies the a-Idrass cf the area containing the messaae text. The 
i^essage may include any characters that can be represented in the 
terminal character set, including blanks, parentheses, and comF.as- 

Spe cified as : In the standard anc! 1-form, a relocatable expres- 
sion; in the staniard and E-fom, register notation (2 through 1?) ; 

I in the r-forra only, an RX address. 

length 
I specifies the address of a fullword that contains the length of 
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I tne message to be issue*-?. If the ijessage is lonaer thai? xhe maxi- 

l EUffi line le!i,qth of SYSOOT, GAT'/* 2 will write as many lines (or rec- 

f ords) as are necessary ud to a maximuirt message length of 512 bytes. 

Specifi ed as : In the standard and L-torro^ a relocatable expres- 
sion; in the staniard and E-form, register notation (2 through 12); 
f in the E-form only, an EX address - 

SIC 

specifies how the characters of the message are to be handled be- 
fore transmission to the user's SYSOUT. The t)rocediire follovei 
vhen SIC is not specified is described in the "Programming ^otes. 
If SIC is specified^ characters with 00 fonction codes are trans- 
mitted to the iiser"s SYSOUT without translation. Control char- 
acters are hand.lei as when SIC is rot specified (the control func- 
tion is perforoted, and the characters are not translated or trans- 
mitted to SYSOUT) . 

Spe cif ied a s : SIC 

Default : Kessage characters are translated and control functions 
are perfortied as iescribed in the Prograpiming ^'otes. 

I Initiali zation : If this macro instruction is to be executed in a privi- 

\ leged module, the most recently issued DCLASS macro instruction in the 

I assembly must have specified Pl^IVILE^ED (see Appendix F) - llso, the 

I address of a save area nust be placed in register 13 before this macro 

I instruction is executed. 

If SIC is not specified, handling of the message characters is as 
follows: 

The Output Character Translation Table consists of two 2S6-byte 
sections; the first section contains the translation table to be 
used for translating the characters of the message, and the second 
section contains function codes that control the handling of the 
corresponding message characters. For 00 function codes, the mes- 
sage characters are translated as determined by the first section 
of the table and transmitted to the user's SYSOUT. Nonzero func- 
tion codes indicate a control function, such as backspace or can- 
cel; when a character with a nonzero code is encountered, the indi- 
cated function is performed, but the character is neither trans- 
lated nor transmitted to the user's SYSOUT. 

The Output Character Translation Table is defined by the system. Howev- 
er, the user may create and use his own translation table; see C ommand 
System User's Guide and the OCTT operand of the KCAST macro instruction 
for more information. 

Return Data : On return from GUTWH, the low-order byte of register 15 
contains the return code shown in Figure 11. 

^ 1 ^ . ^ J 

I Bits 24-31 Code | Significance 



-+ 



08 f Attention interruption occurred; record, if any, is 

f unpredictable. 

I 
10 fSYSOOT is the terminal keyboard. 

1 . I 

Figure 11. Eeturn codes from GATWP and GTWPC macro instructions 
Example : A 16-character record is to be written on SYSOOT: 

EX1 GATIR HECO0T,LEMGTH 
In this example, the user has coded elsewhere in the program: 
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RFCOOI DC C 'COMPLETED ROO}JDl» 

LEiblH DC F'16» 

GDV — Get Def ault Va lue (S) 

The GDV macro instruction, searches the profile member of the user li- 
brary associated with the current user (that is, a private library as- 
signed to each user when he joins the system) to find any predefined pa- 
rameter default values. 

Ml foriLs: 

r 1 1 ^ ^ 1 

fSame | Operation f Operand 



f f[ symbol ] f GDV |[ [parameter address | 'paraEeter •] 1 
I f l[ ,W?=CL| (E, list) I 1 
I I 1 



Mote : if tae f.F operand is oioitted, the standard form is assumed. A 

symbol in the name field is required in the L-form. If the first 
operand is omitted in the L-fora^ it must be supplied with the E-form. 

I parameter address 

f specifies the address of a particular parameter. The actual param- 

I eter '^nsx. be preceded in storaae by its length (one byte) . 

I Specified as: An kJ address, or register notation (1 through 12) . 

I parameter 

I specifies the parameter- 

Specified as : The parameter itself, enclosed in apostrophes. 

J Def ault ; It is assumed that the issuer has placed the parameter 
I address in register 1 - 

In itia li zaxion : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLUSS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M) . Also, the 
address of a save area must be Placed in register 13 before this macro 
instruction is executed. 

Iroqram!kinq no tes: the GDV macro instruction is useful within user- 
coded routines for locating any default values in the user profile. 

The parameter specified by the GDV operand must be the same as the 

parameter indicated in a DEFAULT command - 

GDV is most useful in a routine not associated with any particular 
command -- for which there is no reasonable way to provide a paraneter 
value via a coiamand entry and several levels of call, or for which it is 
not reasonable to associate a parameter with a command, or for which it 
is not reasonable to associate the same parameter with a number of com- 
mands which all use the service routine- (See the BPKDS macro 
instruction .) 

Return Data : If there is no predefined default value in the user li- 
brary corresponding to the parameter name indicated in the GDV macro in- 
struction, register 1 is set to zero and control is returned to the com- 
mand expansion routine. 



120 



PageofGC28-2004-6 
Revised 9 May 1979 
ByTNLGN20-3941 

If the GDV routine finds a default value in the user library, the 
virtual storage address of the default value is placed in register 1 and 
control is returned to the command processing routine (the byte preced- 
ing the default value contains the length of the default value) . 

L - And E-Porm U se: The parameters specified in the E-form of this macro 
instruction will overlay those specified in the L-form. The E-form may 
not specify more operands than are specified in the corresponding L- 
foria. For example: 



SHE 



GD¥ »DPAR1%MF=L 

GDV INSTEAD, rF= (E, SUE) 



INSTEAD 



DC 



C»DPAR2» 



When the E-form of this macro instruction is executed, the oarameter 
specified in the L-form (DP&R1) will be replaced by the parameter speci- 
fied in the E-form CDPAR2) . 

Example ; If a user has created a coacand to be issued at the terminal, 
\ by use of the BPKDS macro instruction and the BOILTI*?! command, the com- 
mand processing routine coded by the user aignt employ the GDV macro in- 
struction as described below. 



f Terminal Commands 
1 


User-Code 


d 


Command 


Processing Routine f 






CSECTA 




CSECT 




1 BUILTIN 


TROT,BPKLABEL 


LABELA 




EQU * 




» 








GD¥ 


■KEYiORD2« 1 


f DEFAULT 


KEYlOaD2=200 


PSECTA 




P5ECT 




1 








BPKDS 


LABELII ,KEIiiOBD1 ,KEYW0PD2 1 


f TROT 


50 






• 





Ihe coiaiiand TRO'T is created by the user, and is issued with a 
defaulted second parameter. In such cases, the coEmand procassino rou- 
tine then executes the GDV macro instruction zo search the user library 
for any defaulted value that may have been previously specified. When 
the default value is located, the command processing routine can then 
I insert the appropriate data into the parapieter list generated by the 
f BPKDS macro instruction an3 continue processina. In the examole above, 
I the defaulted KEYWOED2 operand is found eaual to 200. 



GET — Get a Record m 

The GET ukacro instruction (for VSATI, VISAH, and QSAM) can be speci- 
fied in either locate mode or move mode. In locate mode, the GET aacrc 
instruction locates the next sequential recora of an input daxa set and 
places its address in register 1. The user may then operate on the rec- 
ord where it is, or move it to a work area- In move mode, the GET macro 
instruction acquires the next sequential record an^ laoves it from an 
input buffer to a user-specified area in virtual storage. 
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r— ~ r 1 ^ 1 

fName f Operation | Operand I 

I ^_ 1 ^ 1 

I [ symbol] I GET I deb aidress[ ,area } I 

I . — I I : I 

deb address 

specifies the address of the data control block opened for the data 
set being processed - 

Specified as : Register notation (2 through 12) , or an RX address. 

area (for move mode only) 

specifies the address of the user's work area into which the record 
is moved- The absence of this operand indicates a locate -mode GET. 

Specified a s: Register notation (0 or 2 through 12) , or an RX 

address - 

Initialization : The address of a save area must be placed In register 
13 before execution of this macro instruction. 

CIUTIOHS : 

For VSAH: The contents of reaister 1 are not guaranteed at the con- 
clusion of a move mode GET. 

l or VISiiM : Any exceptional condition (that is, logical record out of 
sequence) resulting from the execution of a GET macro instruction 
causes control to be passed to the user's synchronous error exit 
(SYJAD) routine. In this case, the aeneral registers and the excep- 
tional condition fields in the data control block are set as shown in 
Appendixes B and F . 

The buffer address of the record will remain in register 1 on re- 
turn froB a aove eode GST. 

f or QShli z If any of the following error conditions exists as a re- 
sult of the execution of the SET aacro instruction, control will be 

passed to the synchronous error exit (SYfAD) routine specified in the 
data control block: 

1. ihe next record to be processed starts a block that could not be 

read satisfactorily because of an error condition- 

2. h preceding PUTX macro instruction could not be executed without 
resuJ-ting in an error condition. This situation is discovered by 
the GET macro instruction when workina in update mode. 

3. Khen processing variable-length records, the length of a block 
does not eoual the actual block size. 

4. '^hen processing variable-length records, the lengths of each in- 
dividoal record within a variable-length block io not add up to 
the length indication of the block. 

When the Si:^AD roiitine is given control, the general registers and 
status indicators are set as shown in Appendix B. 

ProqraaEinq Motes: If a GET is requested beyond the end of a data set 
as a result of a sequential operation or SET! macro instruction, the 
user EODAD exit is taken- See l^ppendir C. 
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The GET macro norEally retrieves the recor-i followincr the record ax 
waich the data set is currently Dositioned. However, a GET macro in- 
striiction |>receded.by a S2TL retrieves the record to which the data set 
is positioned by the SETL. 

For VSPJi : For undefined-format records, the user must set the DCBLRE 
■^ field to the length of the record to be retrieved before issuing GET - 
Rules for sharing VS^M data sets are oiven in Appendix K. When 
retrieving vaxiable-lenath records, the GET laacro instruction returns 
with the length of the logical record in the DCBLRE field of the data 
control block. 

For VISAH : A page-level read interlock is imposed on the paoe re- 
ferred to by execation of this macro instructior, . The interlock is 
■ released by any macro instruction referrina to the same BCB that 
refers to another page. " Rules for sharing VISAM" data sets are aiven 
in Appendix K. khen retrieving variable-length records, the GET 
macro instruction returns with the record lenath in the DCBLBE field 
of the data control block - 

F or QS AH : In locate mode, the control T^roaram returns the address of 
the nent logical record in register 1, and places the record length 
in the logical record length (DCBLHECL) field of the data control 
block. In the move aode, the area address provided by the user is 
returned in register 1 and the logical record length of the accessed 
record is placed in DC3LRECL. Because QSA?: does not supoort the 
substitute-mode GET, this feature (that is, return of the area 
aldress) provides compatibility that allows TSS to use the move mode 
in order to execute orograias originally written to use the 
substitute-mode GET. 

Examples : In example 1, move mode, the next record from the data set 
associated yith the DCB labeled STAT is moved to the work area labeled 
SAMPLES. The address of the work area is returned to the user in regis- 
ter 1. 

EXl GET SiAi, SAMPLES 



STAT DCB DSOFG= 
SAMPLES DS 205 



Before execution of the locate node GET in example 2, register 1 is 
loaded with the address of the data control block. After execution of 
the GET, register 1 contains the address of the next seguential record, 
which the user then can move into a work area. 



EX2 LA 1,DCBAD2 
GET (1) 



DCBADR DCB DSOEG= 



GETBUF — Get a Buffer From a Poo l m) 

The GETBUF macro instruction (for BSAS) obtains a buffer froB a spec- 
ified buffer pool. Buffers acquired by a GETBUF must be returned by a 
FREEBUF before they can be obtained again. However, it is not necessary 
to free all buffers prior to issuing the CLOSE iiacro instruction. 
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I , , .__^ 

I ftaiae | Operation | Oper an i! | 

I ^ ^ ^ , 

|[ symbol ]|GBT3UF | deb address ..register | 

I 1 1 . , I 

dCi> address 

specifies the address of tKe data control block opeBed for the data 
set being processed . 

Specified,, as ; - Register notatioit (t through 12), or an RX address. 

register 

SDecifies a reaister into which the contrO'l program is to place the 
address of the buffer - 

Specilied as: An absolute expression. 

C &OTID:^ : Ihe following error conditions result in termination of the 
task: 

1. An invalid data control ■ block is soecified. 

2. ihe buffer size is .or greater than 32,750. 

3. 'ihe number of buffers in the pool is or greater than 255. 

4. The data control block is not o|^en. 

Initialization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instructioii in the 
assembly must have specified PRIVILEGED (see Appendix M) . Also, the 
address of a save area must be i^lacei in register 13 before this macro 
instruci:ion is executed. 

Prpg ra ia aiinq iotes: A buffer pool mast have been assigned to the data 
control block by use of a GETPOOL or by the buffer option in the DCB 
macro instruction (that is, BUFL= and BUP!iO= are supplied in the DCB 
macro instruction) . Each successive GETBOF macro instruction issued 
obtains a buffer in the order in which it exists in the buffer pool. 
For example, if a buffer pool contains five buffers, five successive 
GEXBliF macro instructions would obtain five successive buffers from the 
buffer pool. 

Buffers must be returned to the pool by the FPEEBUF macro instruction 
before they can be obtained again - 

Return Data : If no buffer is available within the pool, the contents of 
the register specified in the GETBUF macro instruction will be set to 
zero rather than to an address. 

ihe address of the buffer pool is placed in the DCBBCH field of the 
data control block - 

Example: The GETPOOI macro instruction is used to define a buffer pool 
of 10 buffers of 100 bytes ^ach. The GETBOF macro instruction is used 
to obtain ^he address of an available buffer in register 5. That buffer 
is then used to hold an input block when a data set is being read. (The 
length operand is not required in the READ macro instruction) . The 
buffer is released by the use of the FPSEBUF macro instruction; the 
buffer pool is eventually released by a FHEEPOOL macro instruction. 
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GETPOOL 



INDCB, 10,100 



OPEH 



(IMDCB, (IMP0T) } 



GETBUF 



IHDCB, iS) 



READ 



DECB1,SF,INDCB, (5) 



FHEEBOF 



INDCB, (5) 



FBEEPOOL IKDCS 



INDCB DCB 



DSORG = PS,. , 



GE!CDV — Get D i ctionary Va l ue (0) 

'Ihe GETD? macro instruction locates a specified symbol in the TSS 
Dictionary and returns a pointer to that value in register 1. 

Note : The GETDV macro plas the SETDV macro give the prograiamer the 
capability ot creating, uplating and deleting entries in the TSS 
Dictionary . 



Name fOoeration f Operand 



-I- 



+ 



IGETDV Iname ,TIPE= {DBFI SYK| CSW] ,COKV= C'ff!!} ,F?= 

_j I ^ 



address of the synbol preceded by a one-byte length field or the 
symbol name in character :foritat. 

Specified as; a one-to-eight character alphameric naae; the first 
character must be alphabetic. 



I1PE= 



the type of entry to search for. 

Specified as : one of the following types: 

DEF - default 

SYN - synonym 

CSk' - comaand syabol word 

Default: DEF 



CONV = 



specifies whether or not the command symbol word is to be conve,rted 
to printable EBCDIC . 
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Specified as ; I (yes) or N (no) 
Defaul t: M 

I nitia l ization : If this macro instruction is to be executed in a privi- 
leged module, the aost recently issued DCLASS macro instruction in the 
assembly must have specified PBIVILE6ED (see Ippendix K) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed, 

Eetu rn codes : register contains the tyoe code of the dictionary 
entry, an^ register 1 contains the address of the dictionary value, pre- 
ceded by a one-byte length. The valid return codes in register 15 are 

as follows: 

Code Meaning 

X«00» successful locate for the symbol 

X'O^* symbol not found 

X"08» incorrect or invalid name given 

X'OC* invalid type given 

Eji aEpl e 1 : 

GETDV ■SYSI11» 

Exaap le 2 : 

LK R3,STF!B0L 
GETD? CE3) ,TYPE = »1>SF» 



DC IL1 CL» SYMBOL) 

SliiEGL DC C'SYSOUT" 

.^STM^AlM -- Get V irtual Sto r age CR) 

The GETf,^Isi macro instruction reguesi^s a contiguous area of virtual 
storage roi a user's task during prograis execution. The areas of virtu- 
al storage allocatel by GETMAI'^ contain binary zeros. 

I 1 1 1 

IName | Operation | Operand i 

I- b— h " 



|[syiLbol](GETMAi:j' f fPAGE[ ,¥AB]f B} , 

I I I f IV={lenqth[ ,FR^class][ ,PACK=iQode]Ml^) } 

I I f[ ,2XIT = RET13Rli ] [ ,RHIMS=] 



P AGE 



¥Atv 



specifies that a number of pages of virtual storage is to be 
allocated. 

Specifxad as : P AG E 

specifies that an additional number of oages is to be allocated. 
This number will have been defined by the installation durina sys- 
teiLi generation. These additional pages are added to those speci- 
fied in tke L? operand. If PAGE,VA.l is specified and LV ±s speci- 
fied as zero, the system generated number of pages (in field ISA- 
¥AR) is reauesi:ed. 
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Spec ified as : ¥ A P 



Lf = 



specifies that a number of byte^ of Yirtwal storage is 1:0 be allo- 
cated. RNAPE Cannot be specified. 

Sp ecified as : E 

specifies the desired number of bytes, oages, or additional pages 
of virtual storage, deoending on whether H, PAGF, or PAGE, ¥AR is 
specified. 

Specified as: An absolute expression or register notation- For 
PAGE requests using register notation format, o nly register 15 is 
allowed- For R requests using register notation, or 2 throuah 12 
can i>e used with the value given as a binary Fuaber placed in the 
low order three bytes of the reaister, right adjusted, an.i the hiah 
order byte of reaister containing binary zeroes in bits 0-3, and 
the protection class in binary in bits 4-7 {see the PF operand) . 
If a recuest is made for a number of bytes that is not a multiple 
of 3, the next higher inultiole of 3 is allotted. 

The length of the specified virtual storage reguest may not exceed 
the amount of virtual storage available at execution tiie . Refer 
to ^he EXIT and BWAfE ooerands- 

Note: See initialization section of this macro for PAGE rea'jests. No 
receding or reassembly is reauired for proorams using the TSS pre- 
Release 2.0 register notation format or this aacro instruction - 

PR = 

specifies the proxection class ro be assigned to the reguested vir- 
tual storage. 

Specified as : 

- User read-and-write 

1 - User read-only 

2 - Private privileged 

Tnis parameter has meaping only for privileged users. If bytes 
were specified and an invalid protection class is specified, a re- 
turn code of X»G3" is placed in register 15. 

Default: 

PACK = 

specifies that the recuested virtual storage is to be put into a 
unique segisant or packed into the first available space- 

Sp ecified as : 

- put into a unigue segment, or pack into the first available 

space, depending on system parameters and the type of reguest 

1 - pack into the first available space, regardless of any svstea 

parameters or the type of reouest 

2 - put into a unigue seament regardless of any system paraKeters 

or the type of reguest 

For the PACK paraiaeter specified as or 2, multiples of 16-page 
requests will be on a 16-paqe boundary, and multiples of 2S6-paae 
reguests will be on a 256-page boundary. 

Default : 
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2XIT=RSTlfRK 

specifies that, if the request for virtual storage cannot be satis- 
fied, a return code of X*04» is Dlaced in register 15- 

Specified as: EXIT=R12*1UFM 

HHAME= 

specifies that the requested virtual storage is to be obtained from 
the reserved segment group. Beserved segment group names are 
eight-character EBCDIC names (refer to the RSVSEG macro 
instruction) . 
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Specified as ; a reserved segment group enclosed within apostro- 
phies; as tlie address of the reserved segment group name expressed 
as a relocatable expression, RX address or register notation. If 
register notation is used, the register soecified must be the first 
of a set of paired registers containing the reserved segment group 
name. 

Default : If this operand is omitted, the system obtains recruested 
virtual storage from any non-reserved segment group. 

Mote: If RNAME is specified, the system will not allocate recru[ested 
virtual storage outside the range of the reserved segment group. Sefer 
to EXIT operand. 

Initialization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLftSS macro instruction in the 
assembly must specify the privilege class of the module which will re- 
lease (FREEKAI!!) the .area obtained. 

Ihis aacro generates the ^DDPG macro in line and uses registers 0, 1, 
and 15 as parameter registers to the ADDPG macro for PAGE requests - 

The format of these registers is: 

Hegister and 1 contain the reserved segment group name. 

Register 15 contains flags and length value as: 

Byte X"01» Variable request 

X»02» System reouested function 

X»04" EXIT=PlTUPIi 

X»f40» HNAME specified 

Byte 1 Bits 0,1 lot used 

Bits 2,3 FackiEg parameter 
Bits 4-7 Protection class 

Bytes 2 ani 3 Clumber of pages requested 

CAUTION: If a reauest for virtual storage cannot be satisfied, and the 
EXIT operand is omitted, an abnormal task termination occurs. 

Procrramminq Hotes : Two seguential GETFIIS macro instructions do not 
guarantee the allocation of two contiguous areas. The only way to en- 
sure a contiguous allocation of n paaes is by issuina a GETHAIN macro 
instruction specifying an area whose length is n. 

No recoding or reassembly ±£ raouired for modules usinc the TSS pre- 
release 2.0 format of this macro instruction. 

Re turn D ata: The address of the allocated virtual storage is returned 
in register 1. The area begins on a page boundary if pages of virtual 
storage were requested, and on a doubleword boundary if bytes were 
reguested. 

If the GETMAIN macro instruction is executed successfully, a return 
code of X'OO* is placed in reaister 15; if the request is unsuccessful, 
the return code is X"04*. 

E xa a £l e : 

EX1 specifies a request for pages and indicates that register 15 has 
been loaded with the number of pages of virtual storage requested (and 
with zeroes in the high-order > bytes of the register) . EXI also soeci- 
fies than a return code of X»04* be issued if the request cannot be 
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satisfied- EX2 regaests allocation of 6 pages of virtual storage. EX3 
indicates a request for pages. Before execution of this macro instruc- 
tion,, the user loads register t5 with the length of the required area 
and loads zeroes in the high-order two bytes of the register- If the 
virtual storage cannot be allocated, the task is abnormally terminated. 
EX 4 requests two more pages than the number specified during system 
generation. EX5 specifies 50 bytes of virtual storage to be allocated; 
the systeit will assign 56 bytes. EX6 specifies a request for pages and 
indicates that register 15 has been loaded with the number of pages and 
that zeroes are in the two high-order bytes of the register. The virtu- 
al storage will be obtained from the reserved segment group whose name 
has been loaded into registers 2 and 3. EX7 specifies a request for ^ 
pages to be obtained from the reserved segment group ■KYBMIKE'. 

EX1 GEIMAIH PAGE,L?= (IS) ,EXIT=Ri'TUEl 

EX2 GETEAIH PAGE,LV=6 

EX3 GBTHAIN PAGE,LV=(15) 

EXa GET'lAIN PAGE,VilR,LV = 2 

EX5 GETKAIM R,L¥=50 

EX6 G^THAIM PAG2,LV= (15) ,PIIAME= (2) 

EX7 GET^IAIS PIGE,lir=a,PMAHE=BNAHE1 



F:HAMS1 



DC 



CL3*KYEHAHE» 



GETPODL 



Get a Buffer. Pool jR) 



The GE'IPOOL macro instruction (for BSAM) requests allocation of an 
area of virtual storage for use as a buffer pool. The buffer pool is 
assigned to the specified data control block. 



I Kase 
I 



(Operation | Operand 



4- 



-f- 



|[ symbol J |G?^TPOOL f deb address, number , length 
I I I -_, 



Icb address 

specifies the address of the data control block to which the buffer 
Dool is to be assianed. 

Specified as: ' register notation (1 through 12) ^ or an RX address. 

n a ruber 

speciries the nusber of buffers to be in the pool. 

Spe cit xed as: Register notation (2 throuah 12) , or an absolute ex- 
pression. The maximum that may be specified is 255. See the 

length operand for the use of (D) . 



lenath 



specixies the number of bytes in each buffer. The value is in- 
creased, if necessary,-, by the GETPOOL routine to be a doubleword 

multiule. 
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S pecified a s: Pegister notation {2 through 12), or an absolute ex- 
pression- The maximum that may be specified is 32,760 bytes- (0) 
may also be used to specify both the number and length operands, in 
which case the number of buffers must be in the two high-order 
bytes of register 0, and the length of each buffer must be in the 
two low-order bytes of register 0, prior to execution of the macro 
instruction - 

CAUTIOM : Failure to observe the following restrictions results in ter- 
mination of the task: 

1. Only one buffer pool may be assigned to a data control block at one 

time. 

2. The buffer length must be less than or equal to 32,760. 

3. The number of buffers must be less than or egual to 255. 

I nitialization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED {see Appendix K) • Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed- 

P rogramming Note s; If the GETPOOL macro instruction is used, it must be 
executed prior to the execution of any GETBUF macro instruction that 
refers to the buffer pool allocated by GETPOOL. 

The FEEEPOOL macro instruction should be issued to return the allo- 
cated buffer pool to tne system, unless a CLOSE is issued for the data 
control block to which the buffer pool is assigned. 

E xamples : EX1 constructs a buffer pool consisting of two buffers, each 
136 bytes long, in an area of virtual storage. This buffer pool is as- 
signed to the data control block REPORT. BX2 indicates that the re- 
quired parameters were in registers 1 and prior to execution of the 
macro instruction. 

EX1 GETPOOL REPORT, 2, 136 
EX2 GETPOOL (1) , ( 0) 

See also the example in the GETBDF macro instruction description. 



I G ETSEG -- Ge t a Page from a Disconnected S egmen t Group (0) 

The GETSEG macro instruction will get a page from a disconnected seg- 
ment group and place it in a buffer specified by the user. 

L-f orm 



r 1 1 

[Name f Operation J Operation 



\ symbol IGETSEG | [ DMAEE = , ] MF=L 
I 1 1 



E-form 



I ^ . , «_ 

I Name fOoeration f Operation 
I 1 , 



I [symbol ]| GETSEG |[DNAME = , ] ADDE ES S=,BUPFER=,MF= (E,list) 

I I L ^ 
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S tandard for m 

f — — ' — , 1 ■ ' 1 

I Name | Operation! Operation I 

|.. ^ j . ^ ^ 1 

I [symbol ]|GETSSG f D^ AM E= ^ilDDBBSS = ^ BUFFER = | 

L . I I I 



!3 ote : All operands are keyword. 

D1IAMB= 

specifies the eight character EBCDIC name of the disconnected seg- 
ment group. 

Specified a s; name enclosed vithin apostrophies: in the E or 
standard form only, as the address of DNAME expressed as a relocat- 
able expression, PX address, or register notation. If register 
notation is used, the register specified must be the first of a set 
of paired registers c ontaining the disconnected segment group name. 

D efault : none. 

C AUTIO N : any user specified DNAME beginning with SYS will be rejected 

by the system. 

ADDEESS= 

specifies the relative page address of the disconnected segment 
group page. 

S pecified a s: in the S or standard form only, the address of a 
word containing the relative page address expressed as a relocat- 
able expression, RX address, or register notation. 

D efault : none 

bUFFER= 

specifies the page aligned address into which the disconnected page 

will be placed. 

Spe cified a s; in the E or standard form only, the address of a 
word containing the virtual storage address expressed as a relocat- 
able expression, RX address, or register notation. 

Def ault : none. 

R eturn codes : upon return from execution of GEISEG, register 15 will 
contain a return code as follows: 

Code M ean ing 

X*00" successful 

X»0 6» DNAME invalid 

XM2" segment not available to user class 

X'16* invalid address 

X*40* system error 

Register 1 will contain the address of the Nameseg Parameter List. 

Note : tne DSECT CHANSG covers the Nameseg Parameter List. 

E xample : 



LA R5,32 32 pages in disconnected segment group 
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SE R6^R6 initialize disconnected page address 

LA 37,W0RKPAGE get address of VM work page 



ABRAILOP DS OH 

GET3EG DNAME=ARRAY1 ,ADDRESS= (RS) ,.BUFFER= {R7) 



A R6,. = F»^09 6» address of next disconnected page 

BCT R5,ARRAYL0P process all pages 



ARRAY! DC CL6»DIARRAY» disconnected segment group name 



GTWAR — Write Record on SYSOUT and Bead R espon se f rom SYSIN IS) 

The GTWAR macro instruction writes a message on the user's SYSOUT, 
then reaas the next available record from the user's SYSIN into the des- 
ignated area of the user's available virtual storage. 

Standard form: 



J 1 J . , ^ ^ 

I Name |Operation | Operand 

I _^ — !„.. ^^ . ^ ^ ^ 

I [ symbol ]| GTWAR | message, length of message , response, 

I f [length of response [, translation code] 

I ^ 1 ^ . L ^ 



L- and E-form: 

I 1 ■ 1 ^ — 

I Name | Operation | Operand 

|. 1 — .^ +„ .,. 



I [ symbol ]f GTWAR ([ message ],[ length of message ],[ response ], 

I I f[length of response][ , translation code] 

I I I ,MF={L| CErlist)} 

I . I . 1 



Mote: A symbol is required in the name field with the L-form. Any of 
the first four operands that is omitted in the L-form must be supplied 

in the E-form- 

message 

specifies the address of the area containing the message text. The 
message may include characters that can be represented in the ter- 
minal character set, including blanks, parentheses, and commas. 

Specified a s; In the standard and L-form, a relocatable expres- 
sion; in the standard and E-form, in register notation (2 through 
12) ; in the E-form only, an RX address. 

length of message 

specifies the address of a full word that contains the length of the 
message to be issued. If the message is longer than the maximum 
line length for SYSOUT, GTWAR will write as many lines (or records) 
as are necessary, up to a maximum message length of 512 bytes. 

Specified a s: Same as the first operand. 

response 

specifies the address of the area into which the input record is to 
be placed . 
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Specified a s: Same as the first operand. 

length of response 

specifies the address of a full word containing the length of the 
expected input record. On return^ the actual record length is 
stored in the address specified by this operand. 

Specifi e d a s: Same as the first operand. 

translation code 

specifies how the characters of the input and output messages are 
to be handled before transmission to the response area or to the 
user's SYSOUT. The procedure followed when no translation code is 
specified is described in the Programming Notes. If a translation 
code is specified, the procedure becomes: 

For input ( response) da ta; All characters (with both 00 and non- 
zero function codes) are transmitted to the response area without 
translation. The functions defined for control characters are not 
performed. 

For output messages : Characters with 00 function codes are trans- 
mitted to the user's SYSO0T without translation. Control char- 
acters are handled as when no translation code is specified (the 
control function is performed, and the characters are not trans- 
lated or transmitted to SYSOUT) . 

Specified a s : 
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SIC or 1 - no translation on input 

2 - no translation on output 

3 - no translation on inpat or output 

D efault ; Translation on input and output. 

Initialization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLISS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

I Programming Motes : GTiAR is executed as a "Mrite with available 

I response*. If the user has bufferei input active CINMODE=S) , the output 

f message data is ignored and not displayed to the user, and the next rec- 

I ord froift the input queue is returned to the program. If the programmer 

f wants to ensure that the message is written and that the innut record is 

I in response to the message, the GTWSR macro should be used. 

I If no translation code is specified, handling of the input and output 

message characters is as follows: 

For inpu t ( respons e) d ata : The Input Character Translation Table 

consists of two 256 -byte sections; the first section contains the 
translation table to be used for translating the input characters, 
and the second section contains the function coles that control the 
handling of the corresponding input characters. For 00 function 
coles, the input characters are translated as determined by the 
first section of the table and transmitted to the input area. !lon- 
zero function codes indicate a control function, such as backspace 
or cancel; when a character with a norzero function code is encoun- 
tered, the indicated function is performed, but the character is 
neither translated nor transmitted to the input area. 

For output messages : The Output Character Translation Table is 
used for output messages in the same way that the Input Character 
Translation Table ±e ufed for input data: to determine whether the 
message characters are to be translated and transmitted to the 
user's SISOOT or whether the message characters indicate that a 
control function is to be executed. 

Both the character translation tables are defined by the system. 
However, the user may create and use his own translation tables; see 
Command System User's Guide and the CTT and OCTT operands of the FCASI 
macro instruction for more information. 

If a continuation is indicated (the record extends over more than one 
print line) , the user must provide a GATBD macro instruction to fetch 
the next portion of the record. 

f I response is truncated only if it is longer than tne length speci- 
I fied. Iruncation begins with the rightmost character. 

If GTkAfi is exacutad in a loop and the user wishes to have the same 
value for the expected record length each time, he must reinitialize the 
length of response field each time GTPAE is to be executed. 

note: Only that portion of the record from the pointer on is available 
to the user. .See Appendix I of A ssembler Progr amme r's Gui de for more 
information on record formats. 

Return Data: At conclusion of execution of the GTI»A2 macro instruction, 
register 15 contains two bytes of coded information (hexadecimal) in 
bits 16-31; see Figure 10 (see the description of GATRD) for these 
codes. On return, the actual record length (in bytes) is stored in the 
address specified by the length of response operand. 
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Example : K 16-byte message (-that is, 16 bytes assigned the translation 
eode in the CTT) is written on SYSOOT and a 120-byte record is read froH 
SYSIN into an area called ABLF- 

EX1 GTWAE ?ICT0E,.LA1BY,JIDLE,.DIZE 

In this example y the user has coded elsewhere in the program: 

VICTGE DC C "COMPLETED FIESTR » 

LAREY DC F»16« 

IDLE BC CL120 

DIkSE DC F»120« 

GTIiRC — lirite Becori on S Y SOOT w ith Carriage Control (S) 

Ike GTWRC macro instruction writes a message on the user's SYSOUT, 
from an area in storage, with an extended FORTHIH carriage control 
character (the interpretation given the character in conversational 
tasks is described below) . The carriage control character is not writ- 
ten (see the programming notes) . 

Standard torn: 



I Name | Operation [ Operand 

I ^ -H— 1 



I [ symbol ]|GTWEC |Eiessage area, message length[,SIC] 
I I 1 . 



and E-form: 



.J J J . ^ 

J Name f Operation (Operand 

I- f h 

f[ symbol ]|GTWRC f[message area ][, message length ][, SIC] 

I I f rME=fL| CE,list)} 

I I I 



M ote : A symbol is reauired in the name field with !!F=I- Any operand 

that is omitred in the L-form wast oe supplied in the B-form. 

message area 

specifies the address of the area containing the message text. The 
message may include any characters that can be represented in the 

terminal character set, including blanks, parentheses, and commas. 

Specixied as: In the standard and L-fora, a relocatable expres- 
sion; in tiie standard and E-form, in reaister notation (2 through 

I 12): in the E-form only, an PX address. 

message length 

specifies the address of a fullword that contairis the length of the 
message to be issued- It the message is longer than the MaxiKun 
line lenqth of SYSOOT, GT'^RC will write as many lines (or records) 
[ as are necessary uy to a Baxiisum message length of 512 bytes. The 
f carriage control character should be included in the length count. 



SIC 



Specified as: Same as the first operand. 



specifies how the characters of the message are to be handled be- 
fore transmission to the user's SYSOOT. The procedure followed 
when SIC is not specified is described in the Proaramming ¥otas. 
If SIC is specified, characters with 00 function codes are trans- 
mitted to the user's SYSOOT without translation. Control char- 
acters are handled as when SIC is not specified (the control func- 
tion is per formed, ani the characters are not translated or trans- 
mitted to SYSOOT) - 
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Specified a s: SIC 



Default : Ilessaoe characters are translate! and control functions 
are performed as described in the ^roqraamiag ?Fotes. 

Initialization: If this icacrc instruction is to be execute J, ±n a privi- 
leged module, the most recently issued DCL?.SS macro instruction in the 
assembly itust have SDecified PRIVIIEGKD (see Appendix 1) . Also, the 
address of a save area must be olaced in register 13 before this Eacro 
instruction is executed. 

Return Bata : "he return codes from GTiiRC are shown in Figure 11 (see 
the description of 3ATWR) . 

Programming )Iotes : When usina GTWHC, a single line passed to the 5ATF 
routine may be up to 511 characters- I'he carriage control character 
must be in the first position of the output line« 

the GATE routine will ensure that all noeconversational SISOOT rec- 
ords will be generated with carriage control characters. !lormallyr for 
nonconversational output from ^ATWR and GTWAR, GATE inserts a blank car- 
riage control character into each record. However, after a given number 
of lines, a skip to channel 1 will be inserted instead. The number of 
lines per page used to control oaqe soace skipoing is 5i|, unless changed 
by a DEFAULT command. 

In conversational tasks, the GATE routine interprets the FOHTSAf car- 
riage control characters {see Appendix D) as follows: 

1. For a "space before printing" character, a number of carriage 
returns one less than the number of soaces reguired are inserted at 
the beginning of the text as a separate aessage- 

2. A "skio to channel" character is treated as a »'triple space before 
printing" character (see 1. above) . 

3. For either "space suDpression" or zero spaces before printing, a 
"single space before printing" character is assumed (thus none of 
the anomalies of the various terminal devices need be recognized) - 

I 4. A screen coaiinand carriage control character (S) for terminals other 
I than 3270s causes the GTWRC to be NOOPei and a successful return is 
I made to the program - 

I 5. A character other than a carriage control character is treated as a 
"single space before printing" character. 

liote: The spacing character at the beoinning of the line is not 
printed . 

E x ant pie ; A 16-character record is to be written on SISOUT: 

EX1 GTWRC HECOUT, LENGTH 

In this example the user has coded elsewhere in the orogram: 

RECOUT DC C»-COKPLETEB ROONDl* skip 3 lines 
LENGTH DC pn7» before printina 



GTWSR — Write Record on SYSOOT and Read Record from Terminal SYSIM (S) 

The GTWSR macro instruction writes a message on SYSOUT and reads the 
response from the terminal keyboard (SYSIH) in conversational tasks 
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only. Use of this nacrO' instructioB in a nonconversational task causes 
termination of the task; however, the message is written on SYSOUT. 

Staniari forsi: 



lliaiie I Operation I Opera n-l 
4— h ^ 



I [ syabol ] JSTSSF | message rlength of message , response , 

f I (length of respofise[ , translation co^e] 



and E-ior!A: 



|Kame | Operation | Operanc 
-I h 



|[ symDol ]|GT^?SF [[ aessage ],[ length of message ],.[ resi>onse ], 

I I I ([length of response 1,[ translation code] 

I I |,f?=CL| (£,list)} 



I 



Jote: A symbol is repaired in the name field with KF=L. Any of the 
first four operands that is onittei from the L-form must be supplied 

with the E-form. 

message 

specifies the address of the area containing the messaae text. The 
message raay include any characters that can be represented in the 
terminal character set, including blanks, parentheses, anc' commas. 

Sp ecif ied as; In the standard and L-form, as a relocatable expres- 
sion; in the standard and E-form , also as register notation (2 
through 12); in the E-form only, also as an RX address. 

length of aiessage 

specifies the address of a fullword containing the lenath of the 
message to be issued. If the nessage is longer than the maximum 
line length for SYSOUT, GTISH writes as many lines (or records) as 
are necessary up to a maximam message length of 512 bytes - 

S pecified as: Same as the first operand. 

response 

specifies the address of the area into which the expected input 
record is to be placed - 

Spe cifi ed as : Sane as the first operand. 

length of response 

specifies the address of a fullword containing the length of the 
expected input record. On return, the actual record length is 
stored in the address specified by this operand. 

Spe cifi ed as: Same as the first operand. 

translation code 

specifies how the characters of the input and output messages are 
to be handled before transmission to the response area or to the 
user's SYSOITT. The procedure followed when no translation code is 
specified is described in the Proaramming Notes. If a translation 
code is specified, the procedure becomes: 

For input (r esponse ) d ata : All characters (with both 00 and non- 
zero function codes) are transmitted to the response area without 
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translation. TMie functions defined for control characters are not 
performed . 

For oatput Bessaqes : Characters with 00 function codes are trans- 
mitted to the user's SISOUT without translation. Control char- 
acters are handled as when no translation code is specified (the 
control function is performed, and the characters are not trans- 
lated or transmitted to SYSOUT) . 

Specified as : 

SIC or 1 - no translation on input 

2 - no translation on output 

3 - no translation on input or output 

Default : Translation on input and output. 

Initialization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGIB (see Appendix M) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed - 

Pr ogra m ming Hotes : If no translation code is specified, handling of the 
input and output message characters is as follows: 

For input ( res p onse ) data: The Input Character Translation Table 

consists of two 256-byte sections; the first section contains the 
translation table to be used for translating the input characters, 
and the second section contains the function coJes that control the 
handling of the corresponding input characters. For 00 function 
codes, the input characters are translate! as determined by the 
first section of the table and transmitted to the input area- Non- 
zero function codes indicate a control function, such as ijacksoace 
or cancel; when a character with a nonzero function code is encoun- 
tered, the indicated function is performed, but the character is 
neither translated nor transmitted to the input area. 

Fo r outpu t messages : The Output Character Translation Table is 
used for output messages in the same way that the Input Character 
Translation Table is used for input data: to determine whether the 
message characters are to be translated and transmitted to the 
user's SYSOUT or whether the message characters indicate that a 
control function is to be executed - 

Both the character translation tables are defined by the system. 
However, the user Bay create and use his own translation tables; see 
Command System User's Guide and the CTT and OCTT ooerands of the FICAST 
macro instruction for more information. 

If a continuation is indicated {the record extends more than one 
print line) , the user must provide a GATED macro instruction to fetch 
the next portion of the record. 

A response is truncated only if it is longer than the length speci- 
I fied by the user. Truncation begins with the rightmost character. 

Return Data : At complatior of execution of the GT'^SR itacro instruction, 
register 15 contains two bytes of coded information thexadecimal) If 
bits 16-31. These codas are shown in Figure 10; however, since this 
macro instruction cannot be executed in nonconversational mode, the nor- 
conversational mode return codes are not issued. 

On return, the actual length of the input record (in bytes) is stored 
at the address specified by the length of response operand. 
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If GTWSR is executed in a loop and the mser wishes to have the same 
value for the expected record length each time, he must reinitialize the 
length of response field each time GTfcSR is to be executed. 

l£i^- Only that portion of the record from the pointer on is available 
to the user- See Appendix C of D ata Management Facili t ies for more in- 
formation on record f omats - 

Example : In the following example, a 16-byte message is written on SYS- 
OUT and a 120-byte record is read from the user's terminal (SYSIN) into 
area RFADIN: 

EXI GTWSR DAEEP ,DLENGTH ,BEIDI11 ,ILEMGTH 

In the example, the user has coded elsewhere in the program: 



OAEEA 


DC 


C •COMPLETED PIESTR* 


OLE^Gia 


DC 


F»16» 


RE AD I M 


DC 


CL120 


ILEHGTH 


DC 


P«120» 



\ HASH — Provide a Hash ¥alue (5) 

The HASH macro instruction provides the issuer with a hash value for 
a specified name (for example, a dictionary entry) . 

I — ^ 1 1 — 1 

IHame | Operation (Operand | 

I h- f ^ 1 

I [ symbol ]f HASH | name, place I 
t I I ^ I 

name 

specifies the address of an eiqht-byte field that contains a name 
of one to eight characters. If less than eight characters, th^ 
name must be left-alioned and padded with trailing blanks. Invalid 
characters will cause a diagnostic error message to be issued. 

Spe cified as: An RX address, or as register notation- If register 
not.arion is used, the address must first be loaded into the speci- 
fied register. 

place 

speciries the address where the one-byte hash value is to be 

placed . 

Specified as : An RX address, or as register notation- If reciister 
notation is used, the address mist first be loaded into the speci- 
fied register. 

Execution: The eight-character string specified in the first operand is 
folded and the result multiplied by 5^^. The product is masked by 127, 
anl the result is iiiultii>lied by 2 . 

Return Data: The low -order byte of the result obtained from the hashing 
algorithcL is placed at the location specified by the second operand . 

IMTIMQ -- Interruption In q uiry (0 ) 

The INTI^iO aacro instruction relinquishes control until more informa- 
tion is available, maintains control in a wait state, or sets up a con- 
ditional branch- It causes an exaninarion of interruption information 
cueued for an interrupt control block (ICB) defined as available to the 
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system by a SIR macro instruction. The IHTliiQ macro instraction can be 
issued only from an interroption routine. 



I 1 J ^ ^ ' ^ " 

IName [OperatioB J Operand 

f- 1 1 

|[ symbol 3IIHTIS0 ficb address 

I I ([ ,HODE= {H|WfCLEx\R| (C, branch address) ,TI^=code} ] 

I t_ I ^ 



icb address 

specifies the address of an IC3 that has been defined as being a- 
vailabla to the systen. by means of a SIR macro instruction. This 
ICi3 should not be one xhat has i>een defined to the systeia with a 
lower priority than the ICB by which current entry to this routine 
was made, if both include the address of the same data control 
block. 

Specified as: Begister notation (2 throuah 12) , or a relocatable 
expression - 

specifies one of four modes of inquiry. 

Specified as : 

E - specifies the interruotion routine is to relinquish control un- 
til lore interruption information of the type specified in the ICB 
associated with the interruption routine is available. If this in- 
formation has already been queued by the system, this routine may 
imikediately regain control. Control is to return to this routine 
at the instruction following the I^TI^IQ macro instruction - 

W - specifies the interruotion routine is to enter a wait condition 
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\ pending availability o^ interrupt information of the type specified 

I by the icb operand. Control is not to be given up althouah the 
I wait condition nay be interrupted by a routine although the wait 
condition may be xnterruptel by a routine of higher priority. At 
the end or the vait, execution is to be resumed with the instruc- 
tion following the IFII^IQ macro instruction. 

CLEAR - specifies that any interruptions oueued for the routine in- 
dicate! by the ICB operanl are to be deleted. Processing is to 
continue with the rext sequential instruction. 

Note : These aueuel interruptions aiay or may not conform with in- 
terruption types currently defined in the ICB. 

C - specifies a branch is to be taken to the location specified by 
the branch address operand, if the information specified bv the TYP 
operand is found in the crueue of interruption information. If it 
is not found, execution is to be resuD:ed with the next sequential 
instruction- The branch address and TIP operands must be written 
if the C option is chosen. 

Default : MOD?!=B 

branch address 

specifies the address to which control is to be transferred if in- 
terruption information of the type specified by the TYP operand is 
available. This operand is only specified if MODE=C is specified. 

Spec ifie d as; Register notation (2 through 12) r or a relocatable 
expression - 

TYi: = 

soecifies the type of interruption information to be the condition 

for the branch. 

Spe cified as : Any of the i:«TTYP codes (as described in the SPEC, 
SAEC, SSEC, STSC, and SEEC macro instruction descriptions) as long 
as the ISTTYP is consistent with the type of ICB defined by the icb 
address operand in this macro instruction. A^Y is written if any 
interruption information of the tyoe specified in the associated 
ICB xs desired. TYP can be something other than the IHTTYP speci- 
fied in the associated ICB. TYP associated with SIEC should speci- 
fy A^Y. 

Initialization ; If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix H) . Also, th,e 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

Brog ramiainq No tes: The INTIMQ macro instruction inspects the crueue of 
interruption information; the subsequent course of action is determined 
by the availability of queued interruption information and the mode 
specified in the macro instrucrtion . Determination of the subsequent ac- 
tion for modes R, W, and C is illustrated in the following chart. Addi- 
tional information pertaining to the IHTINO macro instruction can be 
found under "Writing Interruption Servicing Routines" in Appendix I . 
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f Required 
I iRtermption 
Hode \ Information 



-I . 

I Available 



Action 



Continue execution with next sequential instruction 



I 

I Not available 
I 



Relinquish control; resume execution with next 
seouential instruction when information available 



^ ^ 

I Available 



Continue execution with next seauential instruction 



I 

I Mot available 
I 

-f- — — 



Enter wait state until information available; then 
continue with next sequential instruction 



C I Available 



Branch to specified branch address 



I— 

I Not available I Continue execution with next sequential instruction 

_j«._ i . . 



Beturn Data : Conditions that cause special return codes are listed 
below, with the associated hexadecimal return code. These conditions 
apply only to the modes stated. 

C ode Heani nq 
04 Undefined routine specified (modes C, W, CLEAF) 

08 Erroneous parameter list,, the conditions specified can never 
be met (modes W, C) 

lOREQ — Request an Input/Output Opera tio n CS) 

Tne lOREQ macro instruction (for the lOFEQ facility) initiates an 
input/output operation that is specified by a virtual channel comiaand 
word (¥CCW> . See the description of the ?CCW macro instruction- 
After an lOBFQ Fiacro instruction is issued, control returns to the 
problem program before the I/O operation is completed. The CHECK macro 
instruction ausi: be used to ensure the completion of the I/O operation - 

If an lOREQ macro instruction is used, the IKSK operand of the DCB 
macro instruction must be specified. 



Standard torm : 



J Name 
I 



I Operation [ Operand 

-■I 



-+ : ^ 

f decb nasie, {!i I B] ,dcb address, vcc¥ address, 
I vccw number , starting vccw 



I [ symbol IflORFQ 
I ! 



L- and E-f orm : 



I !laMLe 
I 



I Operation f Operand 



^ ^ 

I decb name,[ {» 13} 1,[ deb address ],[ vccw address], 
|[vccw number ],[ starting vccw }[ ,HF= (L f (E , list) } 1 



|[ symbol JflOREQ 
I t 



r 



Mote : The decb name specified in both the L~ and F-forms identifies the 
parameter list; a symbol is not required in the name field of the L- 
form. Any optional operand that is omitted fro% the L-form must be sup- 

plied with the E-tora. 
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decb nama 

specifies "the name to be assigned to the data event control block 
(DECS) built by the macro expansion. 

Specified as ; In the standard and L-form, a symbol consisting of 
one to eight alphameric characters,, the first of which is alphabet- 
ic; in the E-form, as an RX address , or register notation (1 
through 12) . 



CHfB} 

specifies whether the I/O operation is buffered (a buffer is needed 
to store the data; the request may be nonbuffered if the data buff- 
er in the lOBCB can be used for the data obtained) . 

Specified as : 

N — nonbuffered 

B -- buffered 

deb address 
I specifies the address of the data control block opened for the re- 
I ouested I/O operation. 

Specified as : In the standard and L-foriir a relocatable expres- 
\ sion; in the E-form only, also as an PX address; in the standard 

form or the E-fom, also in register notation (2 through 12). 

¥cc¥ address 

specifies the address of a list of virtual channel command words 
built by the VCCVi macro instruction. 

Specified as : Saae as the deb address operand. 

vccw number 

specifies the number of virtual channel command words in the VCCW 
list. 

Spe cifi ed as : An absolute expression; in the standard and E-form,- 
also in register notation (2 through 12) . 

starring vccw 

specifies the nuffiijer in the list of the VCCi that is to be executed 

first. 

Specified as; An absol^ute expression; in the standard and E-formr 
also in register notation (2 through 12) . 

Initialization : If this macro instruction is to be executed in a privi- 
leged module, the reost recently issued DCLASS macro instruction in the 

assetobly E*ust have specifie.^ ^'HIVILEG^D (see Appendix K) . Also, the 
address ox a save area ptust be olaced in reaister 13 before this macro 
instruction is executed. 

Prograaminq Motes: The lOFSQ macro instruction builr^s a data event con- 
trol block (DECB) , iihos3 address is the symbol coded for the decb naaie 

o'l^erand . 

The format of the DECB is shown in figure 12. 
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Offset 



Siza in f 
aytes I Field 



+0 
+ 1 

+14 
+6 
+ & 
+ 12 
+ 16 
+ 20 
+ 21 
+ 26 
+ 27 
+ 28 
+ 29 
+ 30 
+ 32 
+ 40 



1 J Event control block (ECB) 

3 fHeservad by the system (user must not alter) 

2 I 'Type field (buffered or nonbuf fared lOHEO) 
2 I Length field (for bttfferei only) 

^ |DCB address 

4 I Data area address (for buffered only) 
4 I Pointer to status indicators 

4 fVCCii list a i dress 

2 fOsed by the system (user Eiust not alter) 

1 J Sense byte 

1 fSense byte 1 

1 IVCCW list lenath in doublewords 

1 I Offset from VCCW list in doublewords to starting VCCW 

2 f Reserved by the system (user must not alter) 

3 fKodified channel status wordi (CSW) 

5 I Sense bytes (0-7) 



^Moli 
the 
exce 



ried C 
32-bix 
ption. 



STfl differs only fros CSW in that the first word certains 
address of the instruction causing a unit check or unit 



Figure 12. Data event control block (DECB) format 

The DECB used for lOREQ must not be altered until the operation has 
been checked with a CHECK macro instruction. 

If buffering is specified, the buffers built for read recuest VCCWs 
may have overlapping data areas. However , the complete buffer area 
needed for all the read reouest VCCWs irust be a contiauous area. For 
write request VCCWs, buffer space is allocated for each VCCW, reaardless 
of whether the areas used by the VCCWs have overlapping portions. Con- 
sequently, write request VCCWs do not have to form contiguous areas. 

For buffered VCCW write reouests, the contents of the given data 
address are used when the lOHEQ macro instruction is issued, even if 
these contents will be changed by a read recuest in the VCCW. 

Each lOKSQ macro instruction that causes an input/output remiest to 
be executed accomplishes this request by building an lOPXB. lORCBs are 
executed separately by the system unless they are "chained": chaining 
lORCBs saves time if a following lOBCB channel program is executed be- 
fore the previous IO|?CB's channel proaram is completed. Nontnffered 
VCCW requests use the data buffer in the lORCB . 

If chainina to the next lORCS is desired, the last command to be 
executed must be the last in the user's VCCW list and must have the IOC 
flag set (this i&struction is usually a NOP) . Chaining of lOBCBs is 
accomplished by chanaino the last CCi in a command list to a TIC to the 
START command in the next lORCB. This starting CCW cannot be a TIC, and 
aust be executable only once. lOECB chaiT»ing is allowed only between 
lORCBs on the same device. When chaining is requested, it is still nec- 
essary to check each lOREQ result by using the CHECK macro instruction. 

Return D ata: When execution of the lOREQ macro instruction is complet- 
ed, register 15 contains a hexadecimal return code in its low-order 
by te : 



Code 
00 



Significance 
I/O initiated. 
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04 I/D not initiated. (The "iCT* value in the data con- 

trol block is exceeded^ the DSCB is "active", or the 
DECB is in t^ie "wait" state.) 

08 I/O not initiated. The YCCW list contains an error. 

One of the first nine rales for forming VCCW lists 
has been violated (refer to the VCC1« macro 
insxruction) . 

OC I/O not initiated. The area needed for lOHEQ is too 

large. Eedace or change VCCW list. 

I lI BESE C ri — Loc ate O bje c t Mod\il e in External li brary [SI 

The LIBESECH macro instruction locanes,- in an external library, an 
object iodale that defines a specified symbolic name. 

Standard form: 



I 1 ^ 1 

IJame lOoerationf Operand 



f[ symbol ]|LIBESRCh (list adc'ress, not-found exit 
I I I 



L- and E-torm ; 



I 1 1 

f^ame (Operation (Operand 



([syibolULIBESBCH Iflist aidress ] ,[ not-f ound exit 3,WF= {L | (Enlist) } | 

i I I ^ . 1 

H o|:e : In the L-fors, a symbol is required in the name field- If the 
firsr two operands are not specified in the I-form, they roust be speci- 
fied m the E-form. Operands specified in the E-form overlay corre- 
sDonding operands which were specified in the L-form. In f F= (T^list) , 
list zaust specify the symbol in the name field of the L-form; or the 
syaibol aay be loaded into register 1 and list specifies as (1) . 

list address 

specifies the address of a five-word parameter list tnat you have 
provided. (See Initialization.) 

Specified as: In the standard and L-forHr as a relocatable expres- 
sion; in the standard and E-form, in register notation (2 through 
12); in the E-form only, also as an BX address. If register nota- 
tion is used, the aidress must first be loaded into the specified 
register. 

not found exit 

specifies the address that receives control when a defining module 
is not located or the input library index was zero. 

Specified as: In the standard and L-fora, as a relocatable expres- 
sion; in the standard and B-form, in register notation (2 through 
12) ; in the E-form only, also as an RX address. If register nota- 
tion is used, the address must first be loaded into the specified 
register. 

Initialization : Prior to issuing LIBESECH, parameters must be placed in 
a five-word list whose address is specified in the first operand. The 

list aust contain: 

lord 1 A pointer to an eight- character symbol for which an object 
module that defines the symbol is to be found. 

fciord 2 A library index, that is, a i>ointer to the header of the 

first DCB to be searched in the program library hierarchy - 
The entire program library chain, from the library defined by 
this pointer to and including SYSLIB, is searched until a 
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definition for the symbol is fomnd. (This may also be con- 
sidered an output parameter since it is modified by LIBESRCH 
during processing to point to the current DCB header; see 
"Return Data" below.) 

lord 3 h pointer to a nine-word location you have provided in which 
LIBESECH places information associated with the located 
object module; the information placed in each word is shown 
in Table 2. 

fcords An eight-byte location into which LIBESECH places 
4 and 5 the data definition name associated with the located object 
module. 

CIDT ION S : If you include this macro instruction in a module that is 
declared privileged, (through use of the DCLISS macro instruction) , you 
must place the address of a save area in register 13 before execution. 

If the module in which the symbol is founi is a member of a shared data 
set and you wish to change or erase the member before logoff, a STOi 
macro instruction (type-R) lust be issue'5 to release the read interlock 
set as a result of issuing LIBESRCfi. 

Execut ion : On execution ox the instructions generated by LIBESECH, the 
LIBESEIKCH routine in the dynamic loader searches the program library 
hierarchy for an object module which contains a definition for the sym- 
bol used as an argument (specified by the issuer of the LIBESECH macro 
instruction in the first word of the parameter list pointed to by the 
first operand) . The LIBESEAHCH routine uses the FIND macro instruction 
for the search. 

R eturn Data: If an object module is located, the data definition name 
associat€»d with the program library in which it was found is placed in 
words four and five of the parameter lift provided by the issuer of 
LlBESRCh. A pointer to the header of the bCB that was current when the 
Module was found is placed in the second word of the parameter list in 
place of the pointer provided by the user before issuing IIBESSCH. De- 
tailed information on the object module is placed by LIBESEARCh in the 
nine-word list pointed to by word three of the list Provided by the 
user. Ihis information is rlescribed in Table 2. 

If the second word in the user-provided parameter list is set to 
zero, the object module was not found, and a branch was taken to the 
location specified in the second operand. 

Program ming Notes: ISA location ISAJLC points to the first 'DCB header 
in ztLB library chain (the last-defined J0BLI3) . IS^. location IS^SL^ 
points to the DCB header for SYSLIB. 
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I Word 
I 



Rddress of JPCB for library in which name was located 



I Word 1 
I 



DC3 address for library where name was located 



fiord 2 

I 

I Word 3 

I 



Retrieval address of PMD 



Length of PMD in bytes 



I Word 4 
I 



Retrieval address of text 



I lord 5 

I 



Length of text in bytes 



I Word 6 
I 



Retrieval address of ISD 



I Word 7 
I 



Length of ISD in bytes 



I Word 8 ^SISLIB switch - zero if library where name was located is 
not SYSLIB, nonzero if it is 

I L . 

lable 2. Information returned by LIBESBCH if module located 



LQAI) — Load and Retain a Module {5> 

The LOAD macro instruction is used to load a specified obiect module 
into the user's virtual storage; all other object modules to which it 
(and they) are implicitly linked r are also loaded. The specified module 
cannot be raleasei until the task logs off ^ executes a DELFTE macro in- 
struction, or executes an UiLOID command (refer to Command System User's 
Guide) . l^ota that this macro instruction does not initiate execution of 
the specified orogram. 



-T 1 

f Ooaration \ Operand 



JNamt 



|[ symbol ]|L01D 
I I 



I (EP^entry point I EPLOC=address of adcon grouo] 



EP = 

specifies the symbolic name of an entry ooint in the module to be 
loaded. The name must be the name of a control section, the name 
in the operand field of an assembler language ElfTPY statement, or a 

module Baaa. 

Specified as : A symbol (one to eight alphameric characters, the 
first of which must be alphabetic) . 

EPLOC= 

specifies the address of the explicit adcon group representing the 
module to pe loaded - 

J Specified as : An RX address, or register notation (1 through 12) . 

The aicon aroup can be generated by including in the same program: 

L iDCOa LO?.I),E?=entrf point name 

ProaramiL iBQ H otes: If the module hap already been loaded, this macro 

instructioB is ianoxed. 

The ADDC2I byte (see the descriT>tion of the IDCOJ macro instruction) 
I may be used to direct the dynamic loader to a course of action when the 

speciiie^ ^^odule cannot be loaded. If ADDC2L is set to , the loader 

takes a sys^tem-prescribed error exit. 

It an explicit adcon group is to be used for a LOAD macro instruc- 
tion, it must first be arsed, unless it has not yet been used and it was 
generated by an ABCON macro instruction. (Refer to the ARM and ADCON 
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macro instraction descriptioBs.) If a loa*-ed module has been deiered 
and the user wants to load it again, the same explicit aicon group may 
be reused, pro¥ided it is rearmed. 

I Return D ata : If operand EP= is specified, register 15 contains the 

I address of the specified entry ooint in the loaded module. If operandi 

I SPLOC= is specified, the contents of register 15 are not altered by the 

I execution of the LOAE macro. 

Examples: 1) If a module vhose entry Boint name is POGEP, is to be 
loaded, the following ADCOM macro instruction is specified: 

TEPI ADCON LOAD,E? = IQi;EP 

Opon execution, LOAD EPLOC=TEPI causes the module associated with the 
entry-point name ROGEF to be olaced into virtual storage - 

2) Opon execution of this LOAD macro instruction, a copy of the sodule 
I associated aith the entry-pcint name ALPHA is placed into virtual 

I storage and register IS contains the address of ALPHA 

LOAD EP=ALPHA 

3) Before issuing this LOAD macro instruction, the user loads the 
address of TEEI into register 1- The effect of this instruction is then 
the same as in Example 1 . 

LOAD E?L0C=C1) 

LPCE DIT — Call Edit or froa. L PC (O) 

The LPCSDII macro instruction is used by a language processor con- 
troller to invoke editing facilities for line data sets, or to prompt 
with an underscore for region data sets. 

I 1 1 r 

fName |Ot>eration f Operand f 

¥ \~ » » 

|[symbol]|LPCEDIT f I 

I 1 1 I 

Mote : There are no operands. See Initialization. 

Initialization ; If this macro instruction is executed in a orivileged 
module, the most recently issued DCLASS nacro instruction aiust have 
specified PRIVILEGED (see Sppendix M) . Also, the address of a save area 
must be placed in Register 13 before this macro instruction is executed - 

It is the user's responsibility to set up register before this 
macro instruction is executed, to indicate (by a zero value in the re- 
gister) that the LPC is willing to be iitplicitly ended by the invocation 
of another LPC (a nonzero value indicates that the LPC should not be 
implicitly ended) . 

Programming !lQtes : The LPCEDI'T' macro instruction is issued following 
the LPCINIT macro instraction. As described more fully under "rext 
Editing" in Command System Oser"s Guide ,^ if the key length of the source 
data set is seven, a line data set is assumel and the system prompts 
with the last line number plus 100; editing facilities such as REVISE 
and INSEPT may then be used. If the key length is greater than sbvbji, 
LPCEDIT assumes the user wants to create a region data set and prompts 
him with an underscore to enter a command. 

LPCIMIT — Initi aliz e Edit Co ntro ller for L PC ( S) 

The LPCINIT macro instruction identifies the module in which it is 
issued as a language processor controller; it initializes the text edi- 
tor, allowing the use of system text -editing facilities. 
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Standard form: 



I J 1 — _«„ 

llSaae I Operation I Operand 

I 1 ^- 



J[ sy abol ] I LPCI-'^IT fnaise^dcb aidress y[ transient entry point], 

\ I |[preproc entry point ],[ postproc entry point], 

I I Ifearly end entry point], [scan address ],[trantab ], 

! I I [ enable j, [base ],[ increment ][, implicit end] 



L- and E-form: 

r 1 1 ^ • 

fMame |Op<iration | Operand 

I- 1— 1— ^ 

|[ symbol]! LPCIWIT f[naBe],[dcb address], [ transient entry point], 

I I |[preproc entry point ],[ postproc entry point], 

I f |[earlv end entry point], [scan address ],[traBtab ], 

\ I |[enablel,[ base ],[ increment ],[ implicit end], 

I t |I1?={LJ (5, list)} 

I 1 J 1 

Mote : A syiuboi is reguirel in the name field of the L-form. If either 
of the first two operands is omitted from the L-fori, it must he supp- 
lied with the E-fora. 

name 

specifies the name of the user's lanquaqe processor. 

Sp ecified as: A symbol (one to eight alphameric characters, the 
first of which must be alphabetic) . 

deb address 

specifies the data control block for the source data set. 

Specified as : In the standard and L-form, as a relocatable expres- 
sion; in the standard and E-form, as register notation (2 through 
12); in the E-form only, also as an explicit or implicit address. 

transient entry point 

specifies the address of a three-word field containing the ?-type 
and R-type address constants of the entry point in the user's pro- 
gram to be taken for transient comnaEds, and a pointer to the field 
into which the transient command is to be i.oved (this latter field 
must be preceded by a fullword field containing the maximum length 
that can be real into the specified area) . A transient command is 
a coiLmand with a vertical (f) as its first character. This facili- 
ty enables the user to perform his own command analysis. 

'iihen control is passed to the specified entry point, register 1 
contains a pointer to a pointer to the area containing the tran- 
sient command string. (The transient command statement prefix 
character — see the TR? operand of the MCAST macro instruction — 
will have been stripped off.) The length field contains the actual 
length read in (in the low-order two bytes) and the SYSIN return 
code (in the hiah-order two bytes) . 

Specified as: Same as the deb address operand. 

Default ; A message is returned and the command is cancelled. 

preproc entry point 

specifies the address of a two-word field containing the ¥-type and 
R-type address constants of the entry point in the user's program 
to which control is returned when an EHD command is encountered. 
If there is an active language processor controller (LPC) , and the 
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same or another LPC is acrtivated b? an LPCINIT itacro instruction, 
an EHD command is assumed and the preproc entry Doint is taken 
(this is called an imp licit END) - 

Sp ecified a s; Same as the deb address operand. 

Default: No preprocessor is invoked. 

postproc entry point 

specifies the address of a two-word field containing the V-type and 
E-type address constants of the entry point in the user's program 
to which control is returned after the LPC marks the current lan- 
guage processor complete and Bakes the text editor facilities no 
longer available. 

Specifi ed as; Same as tha deb address operand. 

De faul t: Ho postprocessor is invoked. 

early end entry point 

specifies the address of a two-word field containing the V-type and 
S~type address constants of the entry point in the user"s program 
to which control is passed when the language processor controller 
is terminated other than by an EWD command. 

Spec ified as : Same as the deb operand. 

Def aul t: The preprocessor entry point is used if there is one; if 
not, the current LPC is ended and the postprocessor entry ooint is 
used (if there is none, an error message is returned) . 

scan address 

specifies the address of a two-word field containing the V-type and 
R-type address constants of the entry point of the routine that the 
languaqe processor controller will use to scan new lines as they 
are entered . 

Specified as: In the standard and L-fora, as a relocatable expres- 
sion; in the standard and E-foris, in register notation (2 through 
12) ; in the E-form only, also as an RX address. 

De fault : A zero is placed in the parameter list. 

trantab 

specifies whether a transaction table is to be kept- 

Specified as: I or M 

Default : M (a zero is placed in the parameter list) . 

enable 

specifies whether the language orocespor controller is to run 
enabled or disabled . 

Sp ecified as: Y or N 

Default: II (a zero is placed in the oarameter list) . 

base 

specifies the initial value for the current line pointer. 

Specified as: A riimber that is a multiple of 100. 

Default : A zero is p3_aced in the oarameter list- 



Page of GC28-2004-6 
Revised 9 May 1979 
By TNL GN20-3941 

incremeBt 

specifies the line number increment to be used when none is speci- 
fied in a command. 

Specified a s: A number - 

Default : A zero is placed in the parameter list. 

implicit end 

specifies whether the language processor controller will allow 
itself to be subject to an implicit eni (the LPC is ended because 
another LPCINIT macro instruction initiates the same or another 
LPC) . 

Specified as: Y or H 

Defa ult : Y (if this operand is omitted^ a zero is placed in the 
parameter list) . 

CAOIIOH : Specif ving any value other than I or N for the trantab, ena- 
ble, and isplicit operands causes an error message to be generated- 

Initializarion: If this macro instruction is issued in a privileged 
module, the most recently issued BCLASS macro instruction in the assem- 
bly aus-t have specified PPIVILEGSD (see lopendix M) . Also, the address 
of a save area lust have been place! in register 13 before this macro 

instruction is executed - 

Ee rurn Data : The following hexadecimal return codes are placed in re- 
gister 15 when control is returned to the user: 

k2^ '"lean in g 

00 Successful coiaoletion of LPCIHIT. 

04 A previous LPC is outstandina and has indicated it is not to 
be implicitly ended, and the user, when prompted, chose not 

to override that choice. 

Ot* Specifiei data control block is not open- 

OC Specified read-in area for transient commands is not read- 
write access for the user. 

f ■^^HKRTRit — Indicate Peturn from Called Prooram dp) 

The KARXHTB!J macro instruction turns on the low order bit in the for- 
ward pointer (Sr*! word) of the caller "s save area. This indicates to 

the calling program that the called oroaram has returned. 



J J ^ 

INaiEe fOpetation I Operan3 

h 1 1 ^ 

I IHARKSTRN f 

I ^ I I 



H o te : Taere are no operands. 
Example : 



EnRKRTRN 
+ 01 11(13),X»01» indicate return was done 

Initxalx zat ion : Register 1? iiust be initialized with the address of 
your save area before using this macro. !!AEKRTPH normally follows imme- 
diately after a call-tyoe Skacro. 
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HCAS'J — Modify Character and Svitch Table (S> 



Tlie MCAST macro 
lation Table {In a 
Cnaracter Translati 
function characters 
characters (also in 
charactexs. Tiie CI* 
session profile are 
nal session. If de 
user's profile by i 

111 forms: 



instruction temporarily reolaces the Character Trans- 
user •s session profile) vith a user-specified 
on table (CTT) and temporarily overlays the control 
, such as continuation characters or end-of -block 

the session orof ile) , with new functional control 
1 and the Profile Character and Snitch Table in the 
both overlaid for the Juration of the user's teraii- 
irel, the changes can be permanently recorded in the 
ssuance of the PROFILE command. 



IMaa 



I Operation fOperand 



f[symbol]|rciST 



[CTT=address][ ,EOB=address ][ ,CO J?=address 1 

[ ,CLP=aa3ress ][ ,TBP=^addre3s ][ ,PCC=address ] 

[ ,SSM=address ][ , usri=ad dress ] 

[ ,?L=address,C?=address][ ,KC=address J ,RS=£ddress] 

[ ,.0CTT=aadress1[ ,KF={L| (Enlist)} ) 



Llote : 
m.ay on 
form . 
also " 



A symbol is required in the name field of the L-form. An oDeran«" 
lY be specified in the E-foria if it is also specified in the L- 

If the ¥F operand is omitted, the standard form is assumed. Sea 
.- an i E-Form Use" below. 



CTX = 



specifies the address of a pointer to the 512-byte Character Trans 
latioc Table (CTT) xhat is temporarily to replace the one in the 
user's session profile, (see Co E ntand System User's Gu ide for a dir 
cussion of the CTT) . 



Spcicified as; 



In the standard fori, as a relocatable expression; 



in the standard and S-form, in reqister notation (2 through 12) ; in 
the E-form only, as an RX address - 

Default: The current value is retained. 



EOB= 



C0!I1 = 



CLP= 



specifies the address of the source list en 1-of -block character 
thax is ro replace the one currently existing in the user's session 
profile- This character defines the end of an input block in the 
source list to the Command Analyzer. The value aust be specified 
as X*26". 

Specified as: Same as ths first operand. 

Default: The current value is retained. 

specifies the address of the contir.uation character that is to 
replace the one in the user's session profile. If the last 
character before a carriage return is a control language continua- 
tion character, the line of input is continued past the carriage 
return to include the next line entered at the terminal. The ini- 
tial CONT character is a hyphen, X»60». 

Specified as : Same as the first operand. 

De fault : The current value is retained. 

specifies the address of the control language prefix character that 
is to replace the one in the user's session profile. Entry of this 
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character at xhe tersjiral recruests the system to execute the coa- 
mand follonina the character immediately. Initially, this charact- 
er is defined as an underscore, X'6D«. 

Sp ecified as : Saiae as the first O'Perand. 

Default; The current value is retained. 

TRP=^ 

specifies the address of the transient command statement Drefix 
character that is to replace the one in the user's session profile. 
When the user codes this as the first character of a command in a 
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comiTiand sta-teroent, it is recognized and control is passed t:o a pre- 
defined entry point in the language processor currently being 
executed. The language processor then iirirediately processes -that 
coirmand and either returns control to the next sequential coirinand 
in the coronend statement or performs other processing. The initial 
TRP character is a vertical bar^ X'lF*, 

Specified as ; Same as the first operand. 

Default ; The current value is retained. 

RCC= 

specifies for input the address of the record concatenation 
character that is to replace the previously-defined characters in 
the user's session profile- If cx^ncatenation is active (the user 
has issued DEFAULT CONREC=Tr at his terminal)^ the text editor 
examines the last nonblank character of the input line. When it is 
the concatenation character defined by this operand or defined pre- 
viously, the next input line is added to the line to become part of 
a single record. The system- supplied character is the colon 
CX*7A*). See the RS operand for concatenating output messages. 

Specified as ; Same as the first operand- 
Default; The current value is retained. 

SSM= 

specifies the address of the new dser Prompter System Scope Mask. 
This mask is used in conjunction with the explainable words of roes- 
sages written to the terminal from the system message file. When 
the user requests an explanation for such a word (via the EXPLAIN 
cc^ranand) this mask determines the pattern for searching through the 
hierarchy of word explanations in the message file. Each bit posi- 
tion in the one-byte mask corresponds to a byte in an eight- 
character label or message ID associated with a message containing 
the explainablle word. Each bit that is set on (from right, 7-bit| 
to left, 0-bit > causes a different level message file to be 
searched once. A complete scan is made and all indicated searches 
are executed. 

The number of bytes in the message ID compared in each search is 
equal to tte number of bits to the left of the bit that is set on, 

plus 1, for the bit causing the search to be made. Thus if the 
7-bit were set on, a search of 8 charact.ers wculd be made? if the 

1-bit were set on, a search of 2 characters would be made. The 
search for a particular level of explanation for a message begins 
by scanning the mask from right to left, for bits that are on. If 
the first search does not locatci the desired word, the scan contin- 
ues to the next search -indicating bit, €»tc* ^ until, the complete 
mask has been scanned and all levels of search ha%^e been completed. 
The initial default is X»29*, 

Specified as ; Same as the firs^:, ope rand « 

Default: The current value is retained. 



USM= 



specifies the address of the new User Scope Mask. Each bit repre- 
sents a level at which a search and cougar ison is made to locate 
explainable words in a user-defined message file Clocated in the 
user library) . The user may set this mask according to his own 
search logic (see the SSM operand atove for further information) . 
The initial default value for USM is also X'29'.. 
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PL= 



CP= 



KC= 



MS= 



Specified as ; Same as the first operand. 
Default: !rhe current value is retained. 



specifies the address of a byte contaiiiiiig the leagth of tte Com- 
mand ProH^t String, This length cannot exceed 8. This lei^th ini- 
tiallj reflecrts the 3- character default value of the command prompt 
string operand Csee CP below). 

Specified as ; Same as the first operand. 
Default s The current value is retained, 

specifies the address of a syst^a CoiwBand Proapt String that is to 
replace the one in the user* s session profile. This may be a str- 
ing of up to eight characters. The initial default is an unde- 
rscore followed by a backspace and a carriage-return sijppression 
character CX*7A*), The systeii uses this strii^ to prompt the user 
to enter commands at the terininal. If this operand is specified^ 
the PL operand must also be specified. 

Sfmcified as s Sssme as the first operand. 

Default s The current value is ret^ained. 

specifies the address of a one-byte keyboard/card reader switch.. 
This sititch ii^icates the type of device from which input -will be 
acc^>ted by the system- It may be set with a K for a keyboard, or 

with am E to i'Micate either the keyboard or the card read^er. E 
serves as the default jar.ameter and causes the input device to be 
determined by examining the SYSIN parameter previously established 
in the us-er library ty a DEFAULT command. The SYSIH parameter can 
be set to K or C; it is initially 3et tO' K. The KC operand is ini- 
tially set to E. 

Specified as s Same as the first operawi. 

Default s The current value is retained, 

specific the address of the carriage-return suppression character 
that is to replace the one in the user's sessi-on profile, normally 
a carriage return is exeoited after 'every message written on the 
te-rminal by the GATE routii^; hoi^ver, wl^n this character appears 
as the last character ,in a message, no c^arriage return occurs. 'The 
next message written on the terminal begins where the last one left 
off. The initial value for RS is 'the colcn, X'7A*. Tte suppres- 
sion character is not written ofi SYSOUT, 

Specified bs s Same ^ the first operand. 

Defaults The current value is retained, 

OCTT 

specifies the addr^s of a pointer to the 512-tyte Output Ch.aracter 
Translation Table that is temporarily to replace the system- 
supplied table in the user^^s session profile. iSee Command System 
Oser's Guide for a discussion of the OCTT I. 

Specified as s Same as the first operaai. 

I^fault s The system-supplied table is used. 

1%8 



CAUTION: If a user issues a PIOFILE command via an OBEY macro instruc- 
tion following SCAST, his aser profile will be permanently changed. 
Users should make certain, for subsequent program executions, that when 
communicating with those programs the updated control and functional 
characters are employed . 

Initialization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLiSS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

Programminqr Not es: The Character Translation Table consists of 512 con- 
tiguous bytes- The table is broken into two 256~byte sections. The 
first section contains the internal binary representation for each of 
the possible hexadecimal codes from 00 to FF, in seguential order. The 
second 256-byte section contains the function codes, each displaced 256 
bytes from its related hexadecimal translation code. The available 
function codes and the Character Translation Table are described in Ap- 
pendix C of Coam and System Oser' s Guide ; a copy of the table can be 
found in that publication. A user must generate his new Character 
Translation Table according to the prescribed format. 

Since the KCAST macro instruction allows new interpretations for all 
current characters and control function switches, it should be particu- 
larly useful for text-editing applications, where unioue character in- 
terpretation is desired and line control changes are needed. 

'^ith the varyina line length capabilities of different devices, it 
may become necessary to divide a line of input. The RCC operand can be 
used to accomplish this. For ordinary printed text, a user might make 
this character a space: a line would then be broken between words. 

L - and g-Form Use: An examole of L- and E-forro use is: 

SUE f^CAST HCC=/,KC=K,I'F=L 
aCAST KC=2,Mr= (E,SIIE) 

i^hen the E-form of this macro instruction is executed, the specifica- 
tion of the SYSIN device indicated via the L~form (K) is reolaced by the 
specification indicated in the E-form (F) . The system will then accept 
input from the keyboard and the card reader. 

Exam ple : The user is replacing the Character Translation Table in the 
user's session profile with the characters indicated in the 512-byte ta- 
ble located at NEWTAB. In addition, the end-of-block character in the 
Profile Character and Switch Table in the user's session profile is be- 
ing changed to an asterisk (*) and the command prompt string is beina 
changed to a number sign (#) . 

MCAST CTT=TA3ADBE,E0B=E0BCHAR, 
PL=LMGTHC3,CP=^EiPEFPT 



LENGTHCa 


DC 


ALT (L»!IEWPPFPT) 


.^EWBRMiT 


DC 


C»#» 


EOBCHAH 


DC 


c»*» 


TABADDB" 


DC 


ALB (NSWTA3) 


NEfcTAB 


DS 


0CL5t2 
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MOTS -- Provide Position Feedbac k: (R) 

i'iie BOTE macro irtstmction (for BSHM) causes the relative positioo 

¥ithin a volume of a block just read or vritten to be placed in register 

1. i'his relative position identifies the block for subseguent reposi- 
tioning of the volume- 

KOTS provides a block count for Magnetic tape. For direct-access 
volumes r the count is the track number relative to the beginning of the 
data set portion on the volume and the record number within the track. 

Ihe aO'xE macro instruction nomally provides information for a subse- 

cuent POI!JT macro instruction. 

r 1 1 ^ ^ ^ 1 

|Mafi.e ^Operation f Operand I 

h 1 1— » 

f[ symbol ] [NOTE |dcb address J 

I I —I I 

deb address 

specifies the address of the data control blo^ck opened for the cur- 
rent: operation - 

Specified a s: Register notation (1 through 12), or an RX address. 

CAlillQM : Ikbnormal terminatioTi occurs if the 3ata control block speci- 
fied by the user is not opened. 

for a data set on maqnetic tape, the NOTE macro instruction should 
not be issued for an unlabeled data set or a data set containing non- 
standard labels, if the data set is opened under either of these 

conditions : 

1. I DDEF macro instruction or command has a disposition parameter of 
EDD. 

2. An OP£!l macro instruction specifies RD3ACK . 

The current block count in the data control block is not valid under the 
above conditions. 

For a data set on magnetic tape, a MOTE macro instruction issued af- 
ter a POXST macro instruction , without an intervening PEAD or WFITE 
macro instruction, does not return the relative address of the last rec- 
ord read or written. IIOTE returns the data control block count minus 1, 
if the last 1/0 operation was not a READ (type SB) ; or it returns the 
data control block count plus 1 , if the last I/O operation was a READ 
(type SB) . 

Init ia l ization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRI?ILEGED (see Appendix K) . Also, the 
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address of a save area must be placed in register 13 before this macro 
instruction is executed. 

Proqraitiroinq Notes ; All READ or WRITE requests mist be checked for com- 
pletion before the NCEE macro instruction is executed. The block iden- 
tification provided is always within the current volume. 

Return Data ; Following execution of the NOTE macro instruction^ the 
system places the block identification of the last block read or written 
in register 1. 

The form of the block identification depends on whether a magnetic 
tape or direct access device is being used^ as follows; 

Magnetic Tape ; If magnetic tape is used, the block identification is 
a four-byte block count of the form zzCC, where; 

22 - binary zero l^tesi 

CC - the block ntamber (binary) within the volume. 

The block identification may be used in the POINT macro instruc- 
tion to reposition the magnetic tape to the location of the block. 

Direct Access Device ; If a direct access device is used, the block 
identification is a four-byte value of the form TTRz, where 

TT - the track number relative to the beginning of the data set 

on the current volume (first track equals 0). 
R - the block number on that track (first data block equals 0). 
z - a binary zero byte- 

If the last operation was a WRITE, an additional parameter is pro- 
vided by NOTE, in register 0, in the form zzLL, where; 

zz == binary zero bytes. 

ILL = the number (in binary) of bytes remaining on that track. 

The initial relative address for the first record on a direct 
access device is (TT=0, R=0) . Ihe initial block count for the first 
record on a magnetic tape device that was not opened for RDBACK or 
MOD is (CC=0). The initial block count for the first record on a 
magnetic tape that was opened for RDBACK or MOD is CC minus 1 (CC= 
trailer label block count). NOTE is applicable only to direct access 
and magnetic tape devices. The address that is sent back in register 
1 for any other equipment type is the data control block count minus 
1 and is preceded by two bytes of binary 0. 



OBEY — Execute a Command or Command Statement (O) 

The OBEY macro instruction allows the user to execute a command or 
command statement even though not in command mode. Upon execution of 
the OBEY macro instruction, the command or command statement specified 
via the macro instruction operands is executed? control is then returned 
to the user's program. OBEY may be used anywhere in the user's program. 

Standard and E-Form; 

J. — ^ J. .^ ^ ^^ . -_^ — . , ^ ^ ^^^ 

I Name ] Operation I Operand | 

( ^^ + 4 

I Esymbol] |OBEY | [{address of command| 'command'}] l,MF=(E,list) 1 | 

Note ; If the MF= operand is omitted, the standard form is assumed. 
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L--f orm: 

1 Name | Operation | Operand 

I sywbol I OEEY | C " ccmiiiand ■ , ]MF=L 

L . X J 



a 



addre s s of coicmand 

specifies the address of a fullword that contains the address of a 
location containing the coiranand or command statement character str- 
ing. (The byte preceding the command string must contain the 
length of the string.) 



Specified as : 
through 12) . 



A relocatable expression, or register notation (1 



Default ; If neither the command nor its address is specified, it 
is assumed that register 1 contains the address of the coirroand or 
comm an d s tat ement . 

command 

specifies the command or command statement character string to be 
executed. 



Specified as ; 
apostrophes. 



The command or ccaramand statement itself enclosed in 



Default ; If neither the command nor its address is specified, it 
is assumed that register 1 contains the address of the command or 
command statement and that the byte before the command contains its 
length. 

CAUTION ; If no operand is specified, the address of the command 
character string must have been loaded into register 1 before execution 
of this macro instruction. 

Initial ization ; If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M). Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

Programming Notes ; If the user specifies the address of the command, 
the address must point to the first byte of the command or command 
character string, and the byte that precedes the character string must 
contain a count of the bytes in the character string. No special align- 
ment is required. 

L- and E-Form Use ; An example of L- and E-form use is: 



SUE 



OBEY COMAEDR,MF=L 
LA 1,NAM1 



OBEY 



NAME 


DC 


A (COMADDR) 




DC 


ALKL' COMADDR) 


COMADDR 


DC 


C EXECUTE PROG 2" 



(Where no operand implies that 
register 1 has been previously 
loaded with the address of a 
fullword (NAME) containing the 
address of COMADDR, and the 
ntamber of bytes composing 
COMADDR is in the byte preceding 
COMADDR) 
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DC 
OTHEHCOH DC 



IL1 (L'OTHSBCOM) 
C'EXECUTE PROG3» 



When the E-form of this macro instruction is executed, the program 
specified via the L-fora (PR0G2) is replaced in the command string by 
the program (PR0G3) indicated via the E-form of the macro instruction. 



Example s ; 



OBEY 'PSOCDEF PJIR1» 

OBEY 'EXECUTE MYPROG" 

OBEY »BACK THISPRG* 

OBEY COKJIDDH 
OBEY 



COKADDE 



DC 

DC 



ALI CL'COMADDl) 
C» EXECUTE PROGA" 



Obey a command 



(Where no operand implies 
that register 1 has been 
previously loaded with the 
address of a fullword 
containing the address 
of COFADDR, and the 
number of bytes coiapos^ina 
COMADDE is in the byte 
preceding COKADDR) 



O PEN — Connect a D a ta Set to the S y stem (S) 
The OPE!? laacro instruction: 

• connects one or mora data sets to the system by comoletina the iata 
control blocks containing their attributes, 

• indicates the manner in which a data set is to be processed, 

• creates and catalogs new Vl"* data sets, and 

• initially positions the data set for processing. 

Input labels are analyzed and output labels are created. Control is 
given to exit routines as specified in the ''ata control block's exit 
list (faSAM and QSAM only) . Any number of data sets and their associated 
options may be specified in the OPEN macro instruction. 

Standard form: 



I Hame 



I Operation | Operand 



-4- 



+ 



l[ symbol] I OPEH 
I I 



\ ( {deb addressr , Coption[ , (PER SAD \ LER VE| ])]},... ) 



L-form and E-foria: 



Name f Operation fOperand 



-I ^ 

|[ CCdcb addressf , Coption[ , {PEEEAD | LEAVE} ])]},...), 1 
I!!F={L| (E,liEt)} 



[ symbol 1»0?EN 



Bote: A symbol is required in the name field of the L-form. 

deb address 

specifies the address of the data control block containino the 
attributes of the data set that is to be initialized. 

Specified as: In the standard and L-form, a relocatable e:cpres- 
sion; in the staniard and E-form, also as register notation; ir. the 
E-form only, also as an RX address. 
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option 

specifies the intended method of input/output processing of the 
data set being connected to the system. The processing method to 
be specified is dependent on the data set organization and access 
method that is being used to perform the I/O processing - 

Spe cified a s; The various processing options, their meanings, and 
the access methods with which they can be specified are shown in 
Figure 13. 



r ■ - T ■ ■ ■ ■ ■ T 1 ■ ■' 1 ■ -I ■ -% 

[Option (Meaning I VAM IBSAM f QSAMJ lOREQ [ 
II 1 1 1 1 t 


II 1 1 1 1 f 

IIHPUT [The data set can be used as input [ X ( X f X [ X f 
[ [only. This option is assumed if this[ 1 1 [ 1 
1 1 operand is defaulted. 1 t 1 1 1 
1^ 1 1 1 1 1 t 


r 1 1 1 ! f J 

[OUIPUT |The data set can be used for output f X | X | I [ X | 
[ [only (except for VAM, in which input [ 1 [ [ [ 
f [is allowed) . f f 1 I 1 
11 1 1 1 1 1 


II I 1 1 1 1 
[ISOOT [Both input and output operations are [ X [ X f — | X [ 
[ [allowed. The data set is positioned 1 1 t 1 1 
[ [to the first record. 1 f [ f [ 
> • 1 i 1 1 1 


r 1 1 1 1 1 f 

lOUxIil I Both output and input operations are f X [ X [ — | X | 
[ [allowed. The data set is positioned 1 [ [ f 1 
[ [to the last record. 1 1 1 1 1 
If 1 1 1 1 1 


f~" • ■ 1 ' 1 1 1 r 1 

lUPDAT [The lata set can be updated (see the I X [ X [ X [ X | 

I [note below) . f f [ 1 f 

II 1 I 1 1 1 


f 1 1 1 1 1 I 

IRDEACK |An IMPUT lata set is to be read | — | X | J [ — - f 
[ [backwards. 1 [ [ 1 f 



Fiqure 13. Data set procelssing options 

l0Li:§* Opening a VISAF data set for I^OUT or OUTIjI is eguivalent to 
opening for DPDAT. When a data set is opened for UPDAT, however, 
the user must position to the desired record in the data set. If a 
new VAM data set is being opened for INOUT or INPUT (either re- 
guested or defaulted) , the option is changed to OUTPUT. All other 
options (UPDAT, OUTIN, OUTPUT) are allowed for a new VAH data set. 

D efault : IMPUT 

REREAD [LEAfE 

specifies for compatibility with OS and OS/VS, a parameter that is 
ignored by TSS because volumes are not mounted in parallel. 

Specified as: REREAD or LEAVE, or it may be omitted. 

Init ialization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLSSS macro instruction in the 
assektly must have specific? ?RI?ILEGED (see Appendix M) . Also, the 
address or a save area must be placed in register 13 before this macro 
instruction is executed- 
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C AUTIO !i : The following errors cause the results indicated in Figure 14, 



Erro r 



Eesult 



Opening a data control block that is already open 

Specifying the address of an invalid data control 
block 

Opening a data control block when a DDMAKE in the 
data control block has not been provided 



Opening a privileged data set by a nonprivileged 
user (BSASr QSAM, VPArt and lOREQ only) 

Opening a read-only data set and specifying an 
option other than IIPDT 

Opening a data control block when the DDNAHE in 
the data control block does not correspond to the 
Db^lAiiE in the DDEF macro instruction (or command) 



Bo action 

Task terminated 

!ilo n con vers ation a 1 
task terminated ; 
prompting given if 
task is conversa- 
tional 

Task terminated 
Task terminated 



No neon vers at ion a 1 
task terminated; 
prompting given if 
task is conversa- 
tional 

Task terminated 



Opening a data control block containing an invalid 
DSORG specification 

. . ^ I 

Figure 14. Results of errors in opening a data set 



P rogramming Notes: Any number of data control block addresses and asso- 
ciated options may be specified in the OPEN macro instruction. This fa- 
cility allows parallel opening of the data control blocks and their as- 
sociated data sets, which is more efficient than to open them individu- 
ally. One of the services performed at this time is processing of 
labels of data sets or volumes. 

F or VSAR : lihen a shared ?SAfi data set is opened, a data set inter- 
lock is set according to the option operand. If IHPUT is specified, 
a read interlock is set; if OUTPUT, INOUT, OUTIN , or UPDAT is speci- 
fied, a write interlock is set. Rules for sharing VSAM data sets are 
given in Appendix K. 

F or ¥1SAM : When a shared VIS AW data set is opened, a data set inter- 
lock is set according to the option operand. If INPUT, IljIOUT, OUTIN, 
or UPDAT is specified, a read interlock is set; if OUTPUT is speci- 
fied, a write interlock is set. Rules for sharing ¥ISAK data sets 
are given in Appendix K. 

For BSAM ; If a DCb exit routine or a user-label exit routine is to 
be executed, the exit lisr address must be provided in the data con- 
trol block. The format of the exit list, its use during the opening 
process, and exit routine reguirements are discussed in Appendix A. 

For ¥AFi; A SYNAD EXIT OPTION bypasses the call to ABEND when certain 
errors are detected by OPEN VAK. Instead, control will be returned 
to the SYNAD routine specified in the DCBSYV and DCBSYR fields of the 
DCB. 

In order to use this option the DCBIM80 flag in the DCB must be set 
•on* before issuing the OPEN macro. Should an error occur and the 
SYNAB routine be given control, the cause of the error may be deter- 
mined by examining the DCBEX1 and DCBEX2 fields in the DCB. 
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Example: 




PROGP 
KYDCB 


PSECT 
DCB 



DD NA ^E =AMI DD , S YM AD =PROGSY M 



PROGC 



CSECT 



LA REG ^ MY DCB 

USING CHADCB ,RPG 

01 BCBI,DCBIM80 

OPEN MYDCB 



load addr DCB 

cover with DSECT 

indicate I want control on error 



PEOGSYN 



EXIT 

DS OH 



I 



examine DCBEXI and DECEX2 for error 



BR 
END 



R14 



f Asynchronous ¥AM page out is the system default for writing data 

I pages; that is, task execution will overlap I/O to the data set. To run 

I synchronously, the DCBIN40 flag must be set as shown for the DCBIN80 

f flag in the example above. 

L - and £-Form Us e; The parameters specified in the E-form will overlay 
parameters specitied in the L-form. The E-form may not specify more DCB 
operands than are specified in the L-form. The format of the parameter 
list generated by the OPEN macro instruction is described in Appendix L. 

For example: 



JOE OPEN CBATASST,,MORSEf,,) rMF=L 

DEB OPEN C,,FOSET,,NUSEH) ,MF= (E,JOE) 

When the E-form macro instruction is executed, the data control block 
FOSET replaces MORSET in the parameter list- Data control blocks with 
symbolic addresses DATASET, FOSET, and NUSEM are opened. 

E xam p les : EX1 opens the data control block INVEN as an input data set. 
EX2 opens the two data control blocks INVEN and REPORT with different 
options. EX3 opens the two data control blocks INVEN and MASTER; they 
are opened for input data sets since INPUT is assumed when the option 
operand is omitted. EX4 generates a parameter list for opening INVEN, 
and EX5 opens INVEN. 

(INVEN, (INPOT)) 

(INVEN, (INPUT) , REPORT, (OUTPUT, LEAVE) ) 
(INVEN, , MASTER) 
(INVEN, (INPUT)) ,MF=L 
MF= (E,EXi|) 



EX 1 


OPEN 


EX 2 


OPEN 


EX3 


OPEN 


EX 4 


OPEN 


EX5 


OPEN 



P AUSE " Enter Command Mode (R) 

The PAUSE macro instruction switches a conversational task from pro- 
gram mode to command mode. A PAUSE macro instruction issued in a non- 
conversational task is ignored. During program stoppage, the user may 
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issae any comiiand he wishes directly from the terminal. The task can be 
returned to program mode by issuing a RON command. 

The word PAUSE and any optional message specified in the operand are 

displayed on SISOUT. 

^ ^ ^ , ^ ^ J 

flame | Operation | Operand | 

I" — H \ ^ — 1 

f [symbol ]f PAUSE ({address of messagel •message'} | 

I — — 1 J — » . ^ » 

address of message 

specifies the address of the location in storage that contains the 
text of the message to be issued. The first byte of the message 
must contain the length, in bytes, of the message. 

Specified a s: An RX address, or register notation (1 through 12) . 

message 

specifies the message to be issued. 

Specified a s: The text of the message itself, enclosed in 
apostrophes - 

I nitialization ; This macro instruction cannot be assembled in a privi- 
leged module unless the most recently issued DCLASS macro instruction in 
the assembly specified USER (see Appendix M) or if the DCLASS option is 
USER by default. 

P rogra mm ing Hote s: If the user has control of interruptions before 
issuing a PAUSE macro instruction, the system regains control of them 
until a EUI command is issued. 

E xamples : In EXl the message is supplied as text. In EX2 the message 
is given at location DARRY. 
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EX1 PAUSE •PROG DECISIOH AT STMT L00P3» 
EX2 PAUSE DABEY 

I PIREC -- Program Interruption Protection in System Code C0> 

The PIREC macro instruction validates an address before the address 
is actually used as an oBerand in a program. This protects the PIRIC 
issuer frosi possible addressing exceptions (possibly because a bad 
address was passed to the issuer of PIREC) . PIREC tests an address by 
executing a test instruction set up by the programmer with the address 
as an operana. If the address is invalid, a program interruption 
occurs, and control returns to the programmer's error routine. 

I 1 1 ■ 1 

I Name | Opera tion ( Operand I 

h h- 1 r 

I [ symbol IfPIREC f error exit, instruction location \ 

I I I ^ I 

error exir 

specifies the location of the programmer's error routine that will 
be used if certain program interruptions occur; diagnostic messages 
about the error can be issued by this routine. 

Specifie d as: A relocatable expression or register notation. 

instruciiion location 

specifies the location of the test instruction to be executed for 
validating an address operand. 

Spe cified as : A relocatable expression or regit^-ter notation.. 

Initial ization : If PIP5C is issued in a privileged CSSCT, a DCUSS 
macro instruction with the PRIVILEGED option should be previously coded 
within the CSECT. If PIBEC is issued in a nonprivileaed module, the 
user can accept the USER setting by default. In cases where several 
DCLASS macro instructions have been coded within a CSFCT, the last one 
issued, prior to issuing PIF^C, must have established the appropriate 
setting . 

A copy statement for CKIISA must be issued Drior to issuing PIREC. 

Ex ecuti on ; PILEC tests the global symbol (5CHDCLS) setting — estab- 
lished by default or a DCLASS macro instruction specification — for the 
CliECT in which PIHEC is issued and sets in the ISA, either ISAPPIR or 
ISAlfPIR. Inese flags indicate whether a orivileged or nonpriviieged 
program interruption might occir due to execution of the test instruc- 
tion. The test instruction is then executed via an Execute instruction. 
If its execation generates a urogram interruption, the appropriate ISA 
flag is automatically reset by the system "s interruption processor. The 
processor recognizes program interruptions U (protection check) , ?> 
(addressing error) , and 6 (specification error) , in nonpriviieged code, 
and 5 and 6 in privileged code, and returns control to PIREC for their 
processing- PIREC aaain checks SCH.DCLS and, based on that setting, 
tests the aooropriate ISl flao to see if it has been reset; if reset, it 
indicates that a prograii interruption did occur. If an interruption oc- 
curred, PIREC exits to the user specified error routine. If no proorai 
interruption occurred, PIPEC resets the flag in the ISA. 

P roq ram lain q Motes: PIREC is often used in system modules (for example, 
in BPKD processing) to test adiresses passed to them from users. It 
protects tiie system program, from having urogram interruptions occur due 
to user errors. 

PIPSC can be coded in privileged or nonpriviieged code. Its use in non- 
privileged code can provi3e an efficient way of checking protection 
without using the CKCLS system macro instruction. 
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Some useful rest instructions and the possible reason, or reasons ^ for 
program interruotions resulting from their execution, are listed below: 



yeaning of CO'le 

1 = Unassigned storage 

2 = Fetch orotection in nonprivilege<1 

code 

L 1, 2, or ^ 3 = Storacre orotection in nonprivileaed 

code 

SI 1r 2r 3, or 4 ^ - Word boundary 

LH 1, 2, 5 S = Halfword boundary 

STH 1 r 2, 3, or 5 

For nonprivileged progran interruptions 4, 5, or 6, processing by the 
PIRBC recovery routine overrides any recovery routine already specified 
via a SII: aacro instruction. 

E xample : k system programmer wants to verify an address that has teen 
passed to a system nodule by a user routine. Ee might code: 

DCLASS PRIVILEGED ESTABLISH I!JTFBROFT TYP5 KXPECTBD 



Lft 5,1 POT AbDF. TO BE TESTED IB R"^ 

SfESl- PlRi2C 1EB,,EXE 
+ USING CHAI3A,0 
+ OI ISA^?IR,ISA^PIE>*! SET APPROPRIATE ISA FLAG: BASED OH 

DCLISS 
+ EX 0,EXE EXECUTE "TEST INSTRUCTION" 

+ TM ISAP?IR,ISAP?IRR DID PRIVILEGED PROG. HIT. OCCOR? 
+ BZ ERR YES; BPftNCH IF PROG. IMT. OCCUPT^gD. 

+ m ISAP?IR,255-ISAPPIPE SO: RESET ISA HAGS 

3 CONTINUE ADDRESS IS OK 

EXE iM (5) ,0 "T^ST INSTPUCTIOF" TO BE EXECUTED 

ERR 2T 5,PSECTADD 

PROFIT USER TASK OR MODULE WITH 
DISGHOSTIC MESSP.GS 



PQI MT — Posit io n to a Slock (R) 

The POIMT macro instruction (for BSIF) repositions a magnetic tape or 
direct access volume to a specified block within a data set on that vol- 
ume. Thus the POIMT macro instruction permits reading or writing of a 
seguential data set from any soecified position. 

The BOTE macro instruction nay be used to provide the positioning in- 
formation that is repaired for the POINT macro instruction. 

I 1 1 ^ ^ 1 

IJame J Operation I Operand I 

I- 1 1 » 

I [ symbol ] IPOINT | deb address ^block identification | 

I I i I 

deb address 

specifies the address of the data control block opened for the data 
set being processed. 

160 



PagcofGC28-2004-6 
Revised 27 Nov. 1979 
By TNL GN20-7000 



WRITE 



OUTDECB,.SFrMYDCB^ C^) f 100 



This is the record to which 
the program will reposition, 



CHECK 
FEEEBOF 



OUTDECB 
HYDCB,4 



NOTE 
ST 



MYDCB 
1,SA¥E 



Note the position of the rec- 
ord under consideration. 



GETBUF KYDCB^4 

POINT HYDCB,SAVE 

BEAD INDECB^SF^MYDCB, (4) ,100 



Reposition to the record 
being considered and 
read it ^ 



PR — Print a Data Set CS) 

The PR macro instruction causes the specified data set to be listed 
in nonconversational mode on a high-speed line printer and, optionally, 
I erases it from the catalog when printing is finished. 

I Not e: this macro instruction has one or more operands that can be 

I used only by a systems programmer; these operand (s) are defined and 

I specified in the System Programmer's Guide manual. 

Standard form (see "Operand Strings" in Part II, Section 1): 

I "-T 1 ^ ^ 1 

I Name I Operation f Operand 



[symbol ] 



PR 



{address of operand string 
•DSNAME=data set name 
,STAETNO=starting position] 
,ENDNO=ending position] 
,PRTSP={EDITfl r2f3) 

[,HEADER=H] [ , LINES=lines per page] [,PAGE=P]} 
,ERASE = [Y|M} ] [ ,ERROPT= {ACCEPT I SKIPf END} ] 
,FORK= standard default region name] 
,STATION=station id] 
,FCB=fcb name] [ ,PAPER=paper type] 
,COPIES=(nnn[, (GP, ...)])] 
,FLASH = (overlay name[ , COUNT ]) ] 
,SYSUCS=users sysucs dsname] [ ,BURST= {Y| N) ] 
,COPYMOD=copy modification data set name ] 
,TRC={Y|N} ]} 

,NPRIORTY=t.ransmission priority] 
,NETACCT=network account number] 
,DELIVER=([ prgmrnam ][ ,room ][ ,dept ][ ,bldg ]) ] 
,PRTCL ASS=printing output class] 
,INDEX=indexing offset] 
,EXTWTR=external writer name] 
,KODTRC=table reference character]*} 



Part 2: 



Macro Instructions 161 



PageofGC28-2004-6 
Revised 27 Nov. 1979 
By TNL GN20-7000 

L-form (see "Operand Strings'* in Part II , Section 1) 

I 



Name 



T 1 

Operation f Oper and 



symbol 



PR 



{address of operand string 
I •DSNME=data set name 
[ rSTIRTNO=starting position] 
[ ,ENDNO=ending position] 
C,PETSP = {EDITf 1 |2|3] 

f[,HEADER=H] [ , LIHES = lines per page] [ ,PAGE=P]} 
[ ,ERASE = {Y1 N} ] [ ,EEROPT={ACCEPTisKIP|END) ] 
[ ,-FORM= standard default region name] 
[ ,STITION=station id] 
[ ,FCB=f cb name] [ ^PAPEP=paper type] 
[ ,COPIES=Cnnn[ , (GP, -..)])] 
[, FLASH = (overlay name[ rCOUNT]) ] 
[ rSYSUCS=ttsers sysucs dsname] [ ,BURST={Y| N} ] 
[ ,COPYMOD=copy modification data set name] 
[ ,TRC={yf!l} ]} 

[ ^!lPRIOBTY=transmission priority] 
[ ,NETACCT=network account number] 
[ rDELI?ER= ([prginrnam][ ^room ][ ,.dept ][ ,bldg ]) ] 
[ ,PRTCLASS=printing output class] 
[ pINDEX=indexing offset] 
[ ^EXTWTR=external writer name ] 
[ ,MODTRC=table reference character]*} 
^MF=L 
I I I 

N ote ; A symbol is required in the name field of the L-form. 



E-form: 



«j , 

I Operation | Operand 



I Name 



-I 

|nF=CE,list) 



I [symbol ]| PR 
I I 



address of operand string 

specifies the address of the first operand in the operand string. 

Specified a s: Register notation (2 through 12) or a relocatable 
expression. Note that the operand string can also be specified in 
the standard form of the macro operand as a character string enc- 
losed in apostrophes, as shown. 

f DSNAME 

f identifies the data set that is to be printed; ?AM data sets must 
I be cataloged; BSAM data sets must be defined within the current 
I task by a DDEF command or must be cataloged. 

i Specified a s: a fully qualified data set name. 

I Default : none- 

I STARTNO 

specifies the byte number at which printing is to start for each 
data set record - 

Specified a s: A one-to-six digit number. 

Default : Printing starts with the first byte of each record. 

I Note: in a VISAM data set with no regions, the data begins in po- 

i sition 9. 



162 



PageofGC28-2004-6 
Revised 27 Nov. 1979 
By TNL GN20-7000 

I EHDNO 

specifies the byte number at which printing is to stop for each 
data set record. This end byte is printed.. 

Specified as ; I one-to-six digit number. 

D efault ; Printing continues to the last byte of each logical rec- 
I ord or until the printer line length is reached, whichever occurs 

f first. (The maximum printer line length is 132 characters.) 

f PETSP 

I specifies the number of spaces to be skipped between lines. 

I Specified a s : 

I EDIT - line spacing is controlled by a character in the first byte 

f position of each logical record. The control characters may 

I be either a FORTRAN control character (defined by American 

I National Standard FOBTRAN, ANSI X3. 9-1966) or machine code 

f (see Appendix D) , but must be of the same type throughout 

I the data set. The control character in each record is 

i user-supplied. 

I 1 - one space between lines. 

I 2 - two spaces between lines. 

I 3 - three spaces between lines. 

f Mot e: when EDIT is specified, HEADER, LINES, and PAGE operands 

I must not be specified - 

f Default ; 1 

I HEADER 

specifies that the first logical record of the data set is to be 
repeated on each print page as a header line. The first 132 bytes 

f or the entire first record, whichever is smaller, will be used as 
the header. 

Specified a s : H 

I Default ; no header is printed. 

lines 

specifies the number of lines to be printed on a page. 

I Specified a s: from one to four decimal digits; 9999 is maximum. 

f Default : 5 4 lines are printed on each page. 

f PAGE 

I specifies that pages are to be numbered. 

Specif i ed a s : P 

Default : Pages are not numbered. 

I ERASE 

specifies the disposition of the cataloged data set after the print 

operation is complete. 

S pecified a s : 

ERASE or I - erase the cataloged data set after the print operation 
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is complete. 
N - do not erase the cataloged data set.. 

Default : The cataloged data set is not erased. 

EBEOEOPl* 

specifies the action to be taken if an uncorrectable error is 
encountered while reading a data set record. fhis option applies 
only if the data set to be printed is on tape. 

Specified a s : 

ACCEPT - the error record is accepted. 

SKIP - the error record is skipped. 

END - the print operation is terminated. 

Default ; EHD 

form 

designates the standard setup region of the SYSUCS data set which 

contains the defaults for the desired combination of paper forms^ 

print chain, carriage control tape, etc. 

Specified a s: from one to six characters. 

Default : PAPER. 

STATIOH 

specifies the remote job entry station to which the printed output 
is to be directed. 

Specified a s: one to eight alphameric characters • 

Default ; ID from Task Common is used - 

Not e: this parameter can be specified only if the user was assign- 
ed this capability when joined to the system. 

CHAES 

specifies the name of the character arrangement table to be used to 
load the UCS buffer in the 1403 and 3211, and the translate tables 
and iCGMS in the 3800 printer. For the 3800 only, up to four char- 
acter sets may be specified, separated by commas and enclosed with- 
in apostrophies. 

Specified a s; one to six alphameric characters- 

Def ault ; P11. 

FCB 

specifies the name of the forms control buffer (FCB) region in the 
SYSUCS data set to be used to load the FCB. 

Specified as : one to six alphameric characters- 

Default ; STD6. 

PAPER 

specifies the paper type to be used for this print request. 

Specified a s: one to eight alphameric characters. 

Default : 1PLY. 

COPIES 

specifies the number of copies of the data set to be printed. If 
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the GP operand described below is defaulted, each copy will be one 
complete image of each page of the data set, and copy one will be 
completely printed before copy two is begun, etc. 

Specified a s; a decimal number indicating the number of copies to 
be printed; maximum is 255. 

D ef ault : one copy of the complete data set is printed- 

GP (IBK 3300 Printer only) 

describes how the printed copies are to be grouped. Each group 
value specifies the number of copies of each individual page to be 
printed (in a group) before starting the printing of the next page. 
Dp to eight group values can be specified. No single group value 
can exceed 255, nor can the sum of those specified exceed 255, or 
the value of the COPIES operand, whichever is less. Mote that the 
sum of all GP values (if coded) must equal the COPIES value. For 
example, if C0PIES=6 (1, 3,2) was coded for a three-page data set, 
the sequence of printing the data set pages would be as follows: 

page number sequence for group 1: 123 

page number sequence for group 2: 111222333 

page number sequence for group 3: 112233 

Default ; none.. 

PLASH (IBM 3800 Printer only) 

identifies an overlay (page frame) to be used for printing. 

S pecified a s; a one to eight character alphameric name. 

Default : none. 

COUHT 

specifies (beginning with the first c opy printed) the total number 
of copies to be printed with an overlay. 

Specified a s: a decimal number between 1 and 255. The maximum 
value cannot be greater than that specified for the COPIES operand. 

Default : if PLASH is specified and COUNT is not specified, all 
copies (pages) have the overlay printed. 

SISUCS 

identifies the user's SISUCS dataset name to be used to perform the 
printer setup. 

Specified a s; a fully qualified data set name. 

Default : TSS*****.SYSUCS (0) 

BURST (IBM 3800 Printer only) 

states whether or not the paper output is to go to the (optional) 
Burster Trimmer Stacker . 

Specified a s; Y meaning yes, or N meaning no. 

Default : N 

COPYHOD (IBM 3800 Printer only) 

identifies the data set name that is to be used for modifying the 
printed copy (copies) . 

Specified a s; a fully qualified data set name. 
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Default : no copy modifications are made during printing. 



TEC 



indicates whether or not a table reference character (TEC) is in- 
cluded as the first byte of each output data record (following the 
optional edit control character) . 

Specified a s; Y meaning yes^ or N leaning no- 

Default: N 

NPBIOHITY 

specifies a priority to be used by nodes in determining which data 

sets to transmit next. 

Specified a s: two decimal characters. 

Default: 50 

IIETACCT 

specifies the network accounting number to be used for this 
transmission. 

Specified as : a maximum of eight alphameric characters. 

Default : the value assigned when the user was JOINed to the sys- 
tem; if none^ the default is blanks* 

DELIVER 

specifies a sublist of parameters to identify the recipient of the 
printed or punched output. 

prgmrnam - specifies the programmer's name-. 

Specified a s: a maximum of twenty alpha characters - 

Default : blanks 

room - specifies the programmer's room number. 

S pecified a s: a maximum of eight alphameric characters. 

Default : blanks 

dept - specifies the programmer's department. 

Specified a s; a maximum of eight alphameric characters. 

Default : blanks 

bldg - specifies the programmer's building - 

Specified a s; a maximum of eight alphameric characters. 

D efault : blanks 

PRTCLISS 

specifies the output class for print data sets. 

Specified a s; one alphameric character. 

Default ; A 
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INDEX 

specifies tlie indexing offset to be used when printing on a 3211 
printer at a non~TSS node. 

Specified -a s; two decimal characters. 

Def amlt : 00 

EITMTE 

specifies the name of the external writer to be used at a non-TSS 
node. 

Specified a s: a maximum of eight alphameric characters. 

Default ; blanks 

MODTEC 

specifies a table reference character for use at a non-TSS node.. 

Specified a s: 0, 1, 2, or 3 

Default : none 

I nitialization : If this macro instruction is to be executed in a pri¥i~ 
leged module r the most recently issued DCLASS macro instruction in the 

assemblf must have specified PRIVILEGED (see Appendix H) . Also^ the 
address of a save, area must be placed in register 13 before this macro 
instruction is executed. 

Proqramainq note s: the PE macro instruction assigns the request to an 
independent nonconversationa 1 task, to which the system assigns a BSi 
tor possible reference by the user.. The specified data set is printed 
as it appears- Invalid print characters appear as blanks in the output. 
Data set records containing a read error (or an invalid control charac- 
ter, when the EDIT option is used) are printed in hexadecimal on SfSOOf . 
When the data set resides on seven track tape, the system makes the 
character adjustments required to ensure data validity. 

If the user specified a form number, the system includes that number in 
its instructions to the system operator when the printer is readied for 
operation- 

The data set name specified for a BSAM data set may or may not be cata- 
loged- If not, it is placed in the catalog until printing is completed^ 
and then erased, regardless of the ERASE option. If the data set is 

cataloged^ the ERASE option can be used to erase after printing is 
completed. 

When EDIT is specified, the first byte of each logical record is assumed 
to be the byte following the the control character, which is not printed 
and is not counted when determining where to begin printing a record. 

If the data set to be printed was created via the EDIT or DATA commands, 
the first byte of each record contains an indicator of the origin of the 
record. The PR macro instruction translates the byte to a •€» if the 
record was entered throcigh a card reader and to a blank if it was 
entered through the keyboard- Unless the STARTNO operand is specified, 
this byte is printed as part of the record. If STARTNO is specified as 
2 this byte is bypassed. 

C AUTIOIS : ihen the user issues the PR macro instruction for a BSAl data 
set that is defined in the task, the data set definition is released^ 
and the data set is disconnected from the user's task. 
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f The Pe macro is ¥alid for BSAM, ?SAH, and fISAK data sets only. It can- 

I not be used to print a member of a VPIM data set» However, a ?PAM mem- 

I ber can be copied with the CDS command^ and then the copy can be 

I printed.- 

I I BSAM data set must reside on magnetic tape; a ¥SAM or VI3AM data set 
f must not have undefined (format U) records. 

I The PB macro instruction should not be used for an un cataloged data set 

i that is awaiting bulk I/O because PR causes the uncataloged data set to 

I be automatically erased. 

R eturn Data ; At completion of execution of the PR macro instruction, 
register 1 contains the address of the batch sequence number assigned to 
the nonconversational task established by this macro instruction; the 
low-order byte of register 15 contains one of the following codes: 



Cod e 
00 

oc 



significance 

PR request was accepted. 

PR request was not accepted, 



E xample s : In EXI, the operands are presented as a character string. In 
EX2, a symbolic address designates the location of the operand string. 



EXI 
EX2 



PR 
PR 



•DSHA Mil, 02, 120,1' 
LSTTAG 



Since EX2 specifies an address, the user has provided the operand 
string at location LSTTAG. When the macro instruction is executed, the 
necessary alphameric characters must be available in the string. 



P RHPT — Pro m pt System to Pi splay a Particular Message gS) 

The PRHPT macro instruction requests that the message associated with 
a particular message ID be displayed, at the terminal and calls upon a 
system control program {the Oser Prompter) to handle the request. 

Standard form: 



I Mame 



-T " 1 

fOperation JOperand 



J {address of message idf'message id*} 

I {address of response code (response code], 

I [user response] 

|[, ({address of parameter f •parameter •}#•••) ] 



f [symbol ]fPRKPT 
I f 

I I 

I I 

I ^ L 



L~f orm : 



I Name 



Operation f Operand 



h- 

PRMPT f[ •message id ], [response code], 

I [ user response J , ('parameter •,..•) ],KF=L 



I symbol 
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E-form: 



J ^ — ^ 1 . ^ 

Name | Operation | Operand 

» — ^ 1 

[symbol jlPRMPT ([{address of message id|»message id*}], 

I |[ {address of response code I response code} }, 

f f [user response] 

f |[r ({address of parameter | ■parameter •},«..) ], 

I I MF= (Enlist) 



Note: A symbol is required in the name field of the L-form. The para- 
meters specified in the E-form will overlay those specified in the L- 
form. The E-form may not specify more operands than are specified in 
the corresponding L-form . 

address of message id 

specifies the location of an eight-byte field containing the mes- 
sage identification code (see below) , left-aligned and filled out 
with blanks. 

Specified a s: Register notation (2 through 12) ; in the standard 
form, also as a relocatable expression; in the E-form, also as an 
RX address* 

message id 

specifies a unigue eight-byte message identification code associat- 
ed with a message residing in a user-provided message library. 

Specified as : The identification code itself enclosed in 
apostrophes . 

address of response code 

specifies the address of a location that contains the response code 
(see below) . 

Specified a s: Register notation (2 through 12) ; in the standard 
form, also as a relocatable expression; in the S-form, also as an 
IX address - 

response code 

specifies a one-byte code indicating the types of responses, if 
any, the Oser Prompter program should expect from the terminal when 
the message is displayed at the terminal. 

Specified a s : 

H - No response should be expected from the terminal. This option 
causes the User Prompter to display the message at the termi- 
nal and return control to the program containing the PRMPT 
macro instruction. The user response field is not required 
with this code. 

P - A predefined response should be expected from the terminal. 

This option causes the User Prompter to display the message at 
the terminal, read a user response from the terminal, and then 
compare the user response to an expected response that was 
predefined in the message library. If a matching response is 
received, a code attached to the predefined response in the 
library is returned to the caller in the user response field 
defined by the PRMPT macro instruction. If a matching 
response is not found, the user is prompted with all of the 
predefined responses to terminal responses. For conversation- 
al tasks, if the next response is also improper, the user 
response field is either set to zero and an error is indicated 
in register 15, or, if the response is to be defaulted, regis- 
ter 15 will be set to zero* Control is then returned to the 
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user's program. (See "Response Message" in C ommand Syste m 
User's Guide for the means of defining the responses.) 

R - Return message text. This option causes the user prompter to 
return the text of the message, with the inserts filled in, to 
the program cx>ntaining the PRKPT macro instruction. U'pon suc- 
cessful return fro© the PB HPT macro, register 1 contains the 
address of the text and register contains the length o^f the 
text. The user response field is optional on this call; if 
specified it will contain the address of the text preceded by 
a word containing its length- M ote ; message text is returned 
only if the return code is X'OO* or X"14«; on all other return 
cO'des the contents of registers and 1 are unpredictable. 

U - An unpredictable response other than those defined in the mes- 
sage file, such as a string of information, should be expected 
from the terminal. This option causes the Oser Prompter to 
display a message at the terminal and then read an undefined 
response from the terminal- For example, the message might be 
"Enter User ID", to which the response would be an actual user 
identification* In this case the User Prompter olaces in the 
user response field a pointer to the response read from the 
terminal. The byte preceding the response string must contain 
the length of that string (255 bytes maximum length) . 

user response 

k one-word field in which the User Prompter indicates the type of 
user response to a message. For predictable responses, a unigue 
predefined response code, indicating which of the possible prede- 
fined responses has been entered, is placed in the field, right-- 
justified, by the User Prompter. For unpredictable responses, a 
pointer to the response string is placed in the field. 

Specif i ed a s; In the standard and L-form, as a relocatable expres- 
sion; in the standard and F-form, also in register notation; in the 
E-form only, also as an RX address. 

address of parameter 

specifies the location of a parameter (see below) that modifies the 
message being displayed «- See Examples EX4 and EX5. 

Specified as ; In the standard form and L-form, a relocatable ex- 
pression; in the standard and E-form, also in register notation (2 
through 12) ; in the E-form only, also as an RX address. If a relo- 
catable expression is used, the string zo which it points must be 
supplied by the caller^s program and immediately preceded by a byte 
containing the length of the string. The number of parameters and 
parameter addresses cannot exceed 20. 

parameter 

specifies information that is to be used to complete or alter the 
message being displayed at the terminal. The information is 
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substituted for variables ($1, $2,.-.) in the message text* The 
number of parameters or parameter addresses cannot exceed 20. 
Parameters are separated by commas. 

Specified a s; The parameter itself enclosed in apostrophes. If 
more than one parameter is specified r each must be enclosed in apo- 
strophes and separated by commas. Parameters and parameter ad- 
dresses can be intermingled. 

Initialization ; If this macro instruction is to be executed in a pri¥i- 
leged module^ the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M) . Also^ the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

P rogramming Mote s; The User Prompter is a centralized facility for 
storing and displaying messages, providing explanations of messages ^^ and 
handling responses. This facility is available to both the system and 
user programmers. The message file used by the User Prompter is the 
system message file. The user may add to or alter the message file, 
using the procedure defined in C ommand System User's Guide , GC28-2001. 
All predefined responses set up in the message file must be preceded by 
a unigue identification code . 

Failure to supply variable message data parameters, if requested by 
the message in the message file, will result in the User Prompter 
inserting three asterisks (***) in place of tae missing parameters. 

■ft 

Explanations of system messages displayed at the terminal can be re- 
quested by use of the EXPLAIN command (see the Comm and Sys te m User' s 
G uid e for further details) . 

R eturn Data ; When control is returned from the User Prompter to the 
program containing the PRMPT macro instruction, register 15 contains one 
of the following hexadecimal return codes: 

Cod e Meaning 

00 Successful completion, 

f 04 an I/O error has occurred; either the message file SISLIB 

I (SISMLP) is not open, or a SYNAD/EODAD occurred when the 

I replace code is P. 

10 Kessage filtered by user. 

14 Insufficient output buffer space provided. Message 
truncated . 

13 Explanation not. found in message explanation routine. ^lo 
explanation available' displayed at terminal. 

1C Matching response not found in message response routine. 

20 Response code not specified as M, P, or U. 

28 Attention interruption occurred during I/O operation. 

2C Too many reference messages in a chain - reference looping. 

30 Invalid response code in response line of SYSKLF. 

34 Response message not in SYSMLF (response code is P| . 

L - and E-Form Us e: An example of L- and E-form use is: 
SUE PRMPT MSGIDADR,N, ,MF=L 



PRMPT ■MSGIDB%P,RESP,MP= CE,SUE) 



MSGIDADR DC C'MSGIDA» 
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RESP 



DS 



ihea the E-fom of this macro instruction is executed, the message 
(that is, the message whose ID is ESGIDIk) is replaced in the parameter 
table generated by the L-form macro expansion, by the message specified 
in the E-form fthat is, the message whose ID is MSGIDB) « In addition a 

predictable response will be expected by the User Prompter instead of no 
response at all» 

E xamples : The user code, the message written at the terminal, and a 
user response, are in the examples below. It is assumed that BBE?ITY=S 
so that the message identifications are not printed. 

In EXl, the user has defined the message MSGAA LOOP A executed, no 
response from the terminal is expected and control is returned to the 
user^s program after the message is displayed. 



EX 1 • Oser Program : 

Kessaqe to Termina l; 



PRKPT 'HSGAIISM 
LOOP A EXECUTED 



EX2 expects predefined responses to be entered at the terminal • When 
the user responds by entering VS , the PRMPT routine searches a list of 
predefined responses (via the User Prompter) to find a match.- A unique 
code, identifying which of the possible predefined responses the user 
has entered, is stoxed in the fullword parameter (EESP) in the user's 
program and control is returned to the program. 



EX2: 



User Program : 



PBMPT 'MSGAB * ,P ,EESP 



RESP DS F 

Kessaqe to Terminal : ENTER DSORG 
Response fr o m Termin al : V S 

SX3 expects unpredictable responses to be entered at the terminal. 
Khen the user responds by entering his user ID, the routine determines 

if a ¥alid ID has been entered, and if it is valid, places a pointer to 

the area in which the response is stored, in the user response option 
field (IDCODE) « 



EX3: 



User Program : 



PRMPT 'KSGAC ■ , U ,IDCODE 



IDCODE 
Message to Terminal : 
Response fr o m Terminal : 



DC AL1(L»IDC0DE) 
DS F 
ENTER USER ID 
SRITH3 



EX4 requires no user response; variable message data parameters 
C»100» and the string at PAEADD1) are inserted into the message contain- 
ed in the message file and the completed message is written to the ter- 
minal. Thus, if the message is recorded in the message file as, LINE $1 
IS REGIOM $2 DOES NOT EXIST, the variable entries $1 and $2 are replaced 
by the parameters provided via the operands of the PRMPT macro instruc- 
tion as indicated in EX4 . 



EX1: 



User Program : 



PRMPT »MSGAD« ^B ,, (« 100 • ,PARADD1) 



DC 



AL1 (5) 
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DC 


ALICBCODE) 


DC 


F»B» 


DC 


F'N' 


DC 


F'C* 



PARADDl DC C"AD123" 

Message to Terminal : CZSEB LINl 100 IN REGION 

AD123 DOES NOT EXIST 

In EX5, register notation is used in the response code and parameter 
operands. No response is expected from the terminal and the parameters 
A^ B, and C replace the variable entries $01, $02, $03 in the message. 

EX5: User Program ; LA 3,RECODE 

LA 4,C0DEL0C 
PRMPT "MSGAE'^CS) ,, CA^BCODE^ W)) 



BCODE 
RECODE 
CODELOC 
Message to Teanminal s PARAMETER VALUES ARE A,B,C 



PU — Ptmch a Data Set (S) 

In nonconversational mode, the PU macro instruction causes a speci* 
f ied VISAM or VSAM data set to be punched onto cards on a high-speed 
punch and, optionally, to be erased from the catalog when punching is 
finished. Any contiguous field of up to 80 bytes can be punched from 
each input record of an EBCDIC data set. The specified data set is 
punched as it stands, with no code conversions. 

Note ; Up to 160 bytes per card can be punched in a special column 
binary format, where bits and 1 of each byte are ignored. 

Standard form CSee "Operand Strings* in Part II, Section 1); 

I Name j Operation | Operand j 



[symbol] |PU 

I 
I 



address of operand string ] | 

•data set name,, [start bytel,[end bytej , 
[stacker option! , [{ERASE| Y| NJI 
I \^ [,card f orml * 

- J ^ . 



L-form Csee "Operand Strings" in Part II, Section 1); 

I Name | Operation | Operand | 

I symbol JPU | 'data set name,, [start byte] , [end byte], j 

I I I [stacker option] , [ {ERASe| Y\ N> ] [ ,card form] • ,MF=L | 

Note ; A symbol is required in the name field of the L-form. 

E-form; 

[Name | Operation! Operand { 

^ + ^^:^ ^ ^ 

I [syinbol]|PU |MF=CE,list) | 

Note; Two commas must be coded between the data set name and start byte 
operands. 
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address of operand string 

specifies tlie address of the first operand in the operand string. 
See "Operand Strings" in Part 11^ Section 1. 

Specified as ; Register notation C2 through 12) or a relocatable 
expression. Note that the operand string can also be specified in 
the macro operand as a character string enclosed in apostrophes, as 
shown. 

data set name 

specifies the name of the data set to be ptmched. The data set 
name roust previously have been defined by a DDEF macro instruction 
or command, or must be in the catalog. 

Specified as z The fully qualified name of a non -partitioned data 
set or of a nonpartitioned generation of a generation data group 
(identified by absolute generation name or relative generation num- 
ber) . See "Data Set Name" in Part II, Section 1. 

start byte 

specifies the byte number at which punching is to start for each 
data set record. 

Specified as ; A number. 

Default s Punching starts with the first byte of each- record. 

end byte 

specifies the byte number at which punching is to stop for each 
data set record. 

Specified as ; h number. 

Default ; Punching continues to byte 80 Cor, in binary, to byte 
160) or to the end of the record, whichever occurs first. 

stacker option 

specifies the stacker select or edit option; 

Specified as ; 

1 - indicates pocket number Pi 

2 - indicates pocket number P2 

3 - indicates pocket number P3 

EDIT - indicates that the first i^te of each logical record in 
the data set contains a control character for stacker 
selection. This control character is user-supplied and 
may be in FORTRAN or machine oode, but must be in the same 
code throughout the data set. (See Appendix D.) 

Default ; 1 

ERAaE|¥lN 

specifies the disposition of the cataloged data set after the punch 
operation is complete.. 

Specified as ; 

ERASE or Y - erase the cataloged data set after the punch operation 
is complete. 
N - do not erase the cataloged data set. 

Default ; N 

Note; If ERASE or Y is specified for a shared data set that is 
currently being used by another user, a diagnostic message is is- 
sued and the data set is not erased. 
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card forii 

specifies the punch card forii number of the car-3s to be used for 
tnis Dunch request - 

Specified as: One to rix characters. 

Def ault : The installation's standard card fore, as established at 

system generation, is used- 

Hote: The system does not check the validity of the card form 
specified; therefore, it is the responsibility of the user to con- 
vey tae T^eaning of the specified card form to the system ooerator . 

Initializ atio n : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCI.ISS macro instruction in the 
asseibly must have specified PRIVILEGED (see Appendix M) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

£rograatiEinQ Not es: When the user executes a PO macro instruction for a 
data set defined in his task, the data set is released and disconnected 
from the user's task- The PU macro instruction processes data sets that 
were created by using either the virtual seauential or virtual index 
sequential access method. The data set name aust be in the catalog; if 
not, the user's task is terminated. The ERASE option can be used to 
erase the data set after punching is completed. 

If a data set to be punched was created via the DATA command, the 
first byte of each record contains an indicator for the origin of the 
record- Unless the start byte operand is specified, this byte is 
punched as part of the record upon issuance of the PO macro instruction. 
In such a case, if the record was originally entered through a card 
reader, the indicator byte will be punched as a C; if it was entered 
through a tarminal, the byte will be punched as a blank character. When 
the start byte operand is specified as 2 or greater, the indicator byte 
is bypassed and is not included as part of the punched record. 

f Since the DATASET command prefixes a line number automatically to 
each record of a VISAf! data set read from cards, any fISAH data set that 
is to be read from cards should not contain line numbers. Therefore, if 
an existing VISAB line data set is to be punched on cards and later 

I recreated by reading those cards with a DITISST command, the user should 
be careful to punch out the stored YISAM data set without including line 
numbers. 

Invalid characters aopear as blanks when EBCDIC records are punched. 
If a read error occurs, the record in question is not punched, but is 

written in hexadecimal on SYSOUT. 

R eturn Data: At conpletion of execution of the PU macro iRStruction, 
register 1 contains the address of the batch sequence number assigned to 
the nonconversational task established by this macro instruction; the 
low-order byte of register 15 contains one of the following codes: 

Code Significance 

00 PU reguest was accepted. 

[ All other codes Register IS contains a two-byte system message 

number. 

Exam ples : In Ell, the operands are presented as a character string. In 
EX2, a symbolic address designates the operand string. 

EX1 PU ■DSNAM2,,,020,99,,EBASE» 

EX2 PU CDTAG 
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Since EX2 specifies an address , the user has provided the operand 
string at location CD TAG . When the macro instruction is executed, the 
necessary alphameric characters must be available in the string. 

PUT — Include a Record in an Output Data Set CR) 

the POT macro instruction (for ?SAM, VISAH, and QSAM) can be speci- 
fied in either locate mode or move mode. In locate mode, the PUT macro 
instruction places in register 1 the address of an output buffer- The 
user should subsequently construct at that address the next record to be 
incorporated in an output data set. In move mode, the PUT macro in- 
struction moves a record from a user-specified area in virtual storage 
into an output buffer so that the system laay include the record in the 
output data set. 



I 1 1 

I Name | Operation | Operand 

I ^ 4- 

f[ symbol ] I PUT |d.cb address, record address 

1 1 1 



deb address 

specifies the address of the data control block opened for the data 
set being created or extended. 

Sp ecifie d as : Register notation (1 through 12), or an RJ address. 

record address (for move mode only) 

specifies the address of the logical record to be moved into the 
buffer. 

Sp ecif ied as: Eegister notation (1 through 12) , or an P.X adlress. 

Initialization : The address of a save area must be placed in reaister 
13 before execution of this macro instruction. 

CAUTIOUS : 

F or VISAH and QSA H : Any exceptional condition resulting froia the 
execution of a PUT macro instruction causes control to be passed to 
the user's synchronous error exit (SIHAD) routine- In this case, the 
general register and the exceotional condition fields in the data 
control block are set as shown in Appen^^ixes B and P. 

For VISAK : The PUT macro instruction may only be used with data sets 
that have been opened for OUTPUT. If sore than one DCB has been 
opened for a non-shared data set within a task, the PUT will be 
ignored. 

Return Da ta; In locate mode (for QSAM) , the address of the nei.t buffer 
segment large enough to hold the next logical record is returned in 
register 1 after execution of this macro instruction. 

Programming iotes : 

For VSAK; It is the user's responsibility to store the length of 
each format-U record in the DCBLIS field of the data control block 
before issuing the PUT. This length must be a multiple of «I09S 
bytes. 
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For VSAH and ¥ISA H: For format-? records^ each record must begin 
with a four-byte length field- The user laust place the length of the 
record in the loif-order three bytes of that four-byte field before 
issuing a PUT macro instruction. The high-order byte must contain 
binary zero. Rules for sharing data sets are given in Appendix K. 

F or QSAK : Before executing this macro instruction, the user must 
place the length of the record in the logical record length field 
(DCBLEECL) of the data control block according to the format of the 

logical records,, as follows: 

1« Format-F records: the logical record length is taken from 
DCBLEECL. This field should not be altered after the DCB is 
opened or an incx>rrect length block will be written, causing 
abnormal termination. 

2, Format~0 records: the actual record length must be known before 
the record is constructed, and must be placed in the DCBLRECL 
field. Ibnormal termination occurs if DCBLRECL is greater than 
DCBBLKSI* 

3. Format-? records: For locate mode, the actual record length must 
be placed in the DCBLRECL field, or an estimated record length 

(not less than the actual record length) must be placed in the 
DCBLRECL field. If the estimated record length in DCBLRECL is 

greater than DCBBLKSI , abnormal termination occurs. 

For move mode, the length of each logical record determines the 
amount of buffer space needed-. If the length is greater than 
DCBBLKSI, abnormal termination occurs. The record address pro- 
vided by the user is returned in register 1. Because QSAM does 
not support the substitute mode PUT, this feature (return of the 
area address) provides the compatibility that allows move mode to 
be used to execute programs originally written for OS (where sub- 
stitute mode POT may be used) . 

E xam ples : In the following example, the use of a move mode POT is 
shown. The address of the next logical record to be processed is re- 
turned in register 1 following the locate mode GET macro instruction. 
The record is part of an input data set associated with the data control 

block INDCB. After the record is processed within the input buffer, the 
move mode PUT is used to move the record to an output buffer. Before 

the PUT is executed, the address of the record is placed in register 0. 

The branch instruction is used to reenter the processing loop. 

INfEN GET INDCB 



m 


0,1 


PUT 


OUTDCB, (0) 


B 


IN? EN 



I P OTSEG — Put a Pag e into a Disconnected Segment Group CO) 

I The PUTSEG macro instruction will put a page from a virtual storage 

[ buffer into an existing disconnected segment group. 

( L -form 



I r— ^ — r— — ^ — 

f I Name | Operation | Operation 



I \ symbol fFUTSEG | [ DNAME=, ] MF =L 
I I . I 
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E-form 



^ 1 1 

'Name | Operation | Operation 



f [ symbol ]!?UTSEG |[ DNAME=, ] ADDRES S=^BUFFER=, KF= (E^ist) 

I 1 I 



Standard form 



i ! ^ r ' ^ 1 

I Name | OperationfOper ation I 

|™_. , , 1 

f [ symbol ]| PUTSEG | DHAME= ,Ar)DRESS = , BUFFER= f 

i ■ — . 1 1 ^ I 

N ote ; All operands are keyword. 

DiAlE= 

specifies the eight character EBCDIC name of the disconnected seg- 
ment group- 

Specified as : name enclosed within apostrophies: in the E or 
standard form only, as the address of DIAME expressed as a relocat- 
able expression, RX address, or register notation. If register 
notation is used, the register specified must be the first of a set 
of paired registers c ontainin g the disconnected segment group name. 

Default : none. 

CAOTIQN : any user specified DHA HE beginning with SIS will be rejected 
by the system. 

ADDHESS= 

specifies the relative page address of the disconnected segment 

group page. 

Specified as : in the E or standard form only, the address of a 
word containing the relative page address expressed as a relocat- 
able expression, RX address, or register notation. 

Def ault : none. 

BUFFEE= 

specifies the page aligned virtual storage address of the page to 
I be put into the disconnected segment group. 

I Specified as : in the E or standard form only, the address of a 

t| word containing the virtual storage address expressed as a relocat- 

I able expression, RX address, or register notation. 

'< Default ; none^r 

R eturn codes : upon return from execution of PUTSEG, register 15 will 
contain a return code as follows: 

Cod e M eaning 

X'OO* successful 

X»08* DNAKE invalid 

XM2» segment not available to user class 

X'16* invalid address 

X'40* system error 

I Register 1 will contain the address of the Nameseg Parameter List. 
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f Mote : the DSECT CHAMSG covers the Nameseg Parameter List. 
I E xample : 

PUTSEG DMAHE=D0C1 , ADDRESS =DOCPADDR ,BUFFEE=DOCPMOD 



I DOCPADDE DC F*4096» address relative to start of disconnected group 

f DOCMOD DC A (BUFPAG) address of page aligned buffer 

f DOCI DC CL8«D0CCHMG" name of disconnected segment group 

I In the exaaple above, the contents of the second page in the discon- 
I nected group •DOCCHNG* will be replaced with the contents of BOFPAG. 

P UIX — CVSAH) Replace a Secruential Logical Rec o rd fRl 

The POTX macro instruction (for ¥SAM) allows the user to return an 
updated logical record to an input data set. (See below for the QSAH 
PUTX description.) 



I 1 ^ — 1™""" 

(Name ^Operation | Operand 



I [ symbol ]| PUTX J deb address 

I ^ i I . 



deb address 

specifies the address of the data control block opened for the data 
set being processed. 

Specified a s: Register notation (1 through 12), or an RX address. 

I nitialization ; The address of a save area must be placed in register 
13 before execution of this macro instruction. 

P rogramming Note s: The PUTX macro instruction can only replace a rec- 
ord that was located by a locate-mode GET macro instruction. The data 
control block must be opened for the UPDAT node while using PUTX. The 
user must not change the length of the record during the replacement 
process. 

Rules for sharing VSAM data sets are given in Appendix K» 

PUTX — - (QSA Ml Include a Log ical Record i n an Output o r Updated Data Set 

ill 

The PUTX macro instruction (for QSAM) causes the next logical record 
contained in a buffer area of an input data set to be written as the 
next seguential logical record of an output or updated data set- This 
macro instruction may be specified in either update mode or output mode. 
In update mode only, the output and input data sets are one and the 
same, and only the first operand is reguired- In output mode, two dif- 
ferent data sets are used, requiring that both operands be specified, 
(See above for the VISAW PUTX discription .) 



J , ^ ««i ^ — 

I Name [Operation f Operand 



f [symbol ]|PUTX | output deb address [, input deb address] 

I i J . . ^ ^ . — ^ 



output deb address 

specifies the address of the data control block opened for the out- 
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put data set. The output data must be opened for UPBAT if the upd- 
ate mode is used or it must be opened for OUTPUT if the output mode 
is used - 

Specified a s: Register notation (1 through 12), or an RX address. 

input deb address 

specifies the address of the data control block opened for the 
input data set. This operand is required in the output mode. 

Specified a s: Register notation (0 or 2 through 12) , or an BX 
address . 

C AUTIOUS ; The following cautions apply: 

• The data set must reside on a direct access device. 

• For blocked-format records, if any logical record in a block has 
been returned by a PUTX macro instruction, the control program will 
not write the entire block back to the data set until all the logi- 
cal records in that block have been processed - 

• The length of the block and the length of each logical record cannot 
be altered. 

• Additional logical records cannot be inserted in the block, nor can 
existing logical records be deleted from the block. 



174.2 



Programming Not^ ; Any exceptional condition resulting from the execu- 
tion of a PUTX macro instruction causes control tc be passed to the 
user's synchronous error exit CSYNAD) routine. 

Ihe PI3TX macro instruction must always he preceded by a locate mode 
GET macro instruction. This GET macro instruction must specify the same 
data set as specified by an update mode PUTX macro instruction, or it 
must specify the data set that is used as input by an output mode PUTX 
macro instruction. 

Since the update mode uses only a single data set^ the user need only 
issue a PUTX for those logical records that are to be updated. Those 
records that have not changed can be i^passed^ and thereby remain 
unchanged, simply by issuing two successive GET macro instrix^tions Csee 
the example below, ) 

In output iiH^de two distinct data sets are used and a PUTX is required 
for each logical record that is to be included in the output data set 
being created. Abnormal termination occurs if these requirements are 
violated. 

Compatible Record Formats And Buffering Techniques s Normally, when the 
PUTX macro instiruction is used, data sets with the same record formats 
and buffering techniques are processed together. However, the control 
program supports certain variations from this procedure. Figure 15 in- 
dicates which combinations of input and output record formats are 
acceptable. 



r — 



Input data set (locate mode) | to U^ 

from U I S 

from F I S 

from FB \ S 

from V I S 

from VB I S 



h 



Output data set (move mode) 



to F^l to FB^I to V3 I to VB^ 



S 

s 



s 
s 



X 




where ; 



U 

F 

FB 

V 

VB 



indicates unacceptable record format combination 

indicates acceptable record format combinations (only simple 
buffering is supported by TSS) 

indicates forma t-U records 

indicates forma t-F records 

indicates forma t-F blocked records 

indicates forma t-V records 

indicates format-V blocked records 



^The block size for the format-U output data set roust be as large as 
the largest logical record size of the input data set. 

^The logical record size for forroat-F and -FB records must be the 
same for both data sets. 

^The maximum logical record for format-V and -VB records must 
correspond- 



Figure 15. Acceptable record formats for QSAM and the POT*X macro 
instruction 
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Example ; The following example shows the use of a PUIX macro instruc- 
tion when records are being updated. The locate-irode GIT macro instruc- 
tion provides the address of the next record to be updated. The PUTX 
macro instruction^ after processing the record, rettjrns it to the data 
set. The conditional branch instruction tests the condition code. If 
the record is to be updated, the next sequential instruction is 
executed; if it is not to be updated, another GET macro instruction is 
issued to locate the next record. The unconditional branch following 
the PUT macro instruction is used to reenter the processing loop. When 
all input records have teen processed, the EODAD routine is given 
control . 



LIS GIT DCIA 



BH LLS 



PUTX BCBA 



B LLS 



RUE — Restore and Enable (O) 



The RJ^E macro instruction restores the prior inhibit state of the 
task monitor and sets the problem program in the enabled state. 



^ — . ^ ^ ^^ , ^_. 

\ Name | Operation! Operand 

I [symbol] |RAE | status byte address 



I 

™ f 

I 



status byte address 

specifies the address of a one-byte area previously used by an Shi 
macro instruction for saving the prior task monitor inhibit status. 

Specified as : Register notation (2 through 12), or a relocatable 
expression. 

Default ; The restore function is not executed but the problem pro- 
gram is set in the enabled state- 

Initialization ; If this macro instruction is to be executed in a privi- 
leged module, the most recently issued ECLASS macro instruction in the 
assembly must have specif led PRIl^ILEGED (see Appendix M). Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

Programming Notes ; There are separate enable indicators for privileged 
and nonprivileged programs. The RAE macro instruction sets the appro- 
priate indicator, depending on the attributes of the program being 
assembled. A nonprivileged program cannot inhibit dispatching to privi- 
leged programs. 
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READ, ,- — (V15AM) Rea d a Sele cted L ogi cal Record fS) 



The READ ©aero instruction (for ?ISA?!) moves a selected logical rec- 
orl from an input data set to a user -specified area. The user selects 
the record by providina either the recorc" key or the retrieval address. 
(See belO'M for the BSkH F^AD .^escri|>tioii .) 

Standard form: 



I 1 1 • ^ 

[Mame | Operation f Operand 

!„ _! +_: ^ ^ 

I [ symbol ]|REAI> | decb naaer"t¥PeFdcb address, work area address, 
I I (key field address 

I -_«— . ™^ I „ . i . ■ ^ — -._ ..^ . ^ -.- 



and i!;-roras: 



I 1 ^ — I — ^ 

li^ame f Operation f Operand 



I [ synbol j|?E?.D | decb name rtype,[ deb address ],[ work area address] 
I f ![#key field address 1,!1F= (I f E} 



Mote : : A syiaboi is requirei in the name field of the L-fors- If an 
oDerand is not specified with the I-forB, it must be provided with the 

E-f orm. 

decb naiLe 

specifies the name to be assigned to the data event control block 
(DECB) constructed as part of the expansion of this macro instruc- 
tion. The DECB is illustrated in Appendix B, Figure 15. 

Spe cifie d as: One to eight alphameric characters, the first of 
which must be alphabetic; in the E-form only, reoister 1 may also 

be specified. 

type 

specifies the type of HEAD operation. 

Spec ified as : 

KX - read accordinti to specified key ("Read Exclusive") , permittinq 
no other user sharing the data set to gain access to the rec- 
ord until rhe current user has released the record. The rec- 
ord must be released by the RELSX macro instruction or by a 
subsequent WRITS macro instruction referring to the same data 
control block. 

KY - read according to specified key - 

KZ - read according to specified retrieval address. 

deb address 

specifies the address of the data control block opened for the data 
set being processed - 

Sp ecifie d as: In the standard and L-fora, as a relocatable expres- 
sion; in the standard and E-form, also as register notation (2 
through 12) ; in the E-for® only, also as an RX address. 

work area address 

specifies the address of an area in virtual storage into which the 
record is to be placed. 
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Mote : IMie area must be large enough to contain the largest expect- 
ed record. 

Specified as; Same as the deb address operand. 

key field address 

specifies the address of the field containing either the record key 
for a READ (type KY or KX) or the retrieval address for a BEAD 
(type KZ) . The retrieval address is a four-byte field, beginning 
on a word boundary, that is in the data control block and may be 
accessed using the DCBD macro instruction and the name DCBLPA- 

Specifi ed as; Same as the deb address operand - 

I nitializat ion; If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PIIVILIGED (see Appendix P) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

CAUIIQ N: A R^AD by retrieval address (type KZ) must not be use5 with a 
shared data set. 

Exceptional conditions resulting froiL the exiecution of a RFAD macro 
instruction cause control to be passed to the user^s synchronous error 
exit (SIHAD) routine; these conditions include "key not found", "key 
greater than last key on data set," and "invalid retrieval address." 
For these conditions, the general registers and the exceptional condi- 
tion fields in the data control block are set as shown in Appendixes B 
and F. 

P rogramming Hot es; BEAD (type KY) iaposes a page-level read interlock 
on the pages containing the record to be read, whereas READ (type FX) 
imposes a page-level write interlock ani releases a page-level read 
interlock- As the record pointed to by the data control block shifts 
within the data set, page-level interlocks are released from pages no 
longer being used. 

Rules for sharing viSAIi data sets are qiven in Appendix K. 

L- a nd E-Forsi Ose: The L-form macro instruction results in a macro 
expansion consisting of only a parameter list (DECB) - The format of the 
DSCB is described in Appendix B- 

The E-form macro instruction results in a macro expansion consisting 
of only executable instructions. The E-form macro instructioii uses the 
DECB built for it by the L-fora macro instruction. Only MF=S should be 
specified for the MF operand of the E-form, because it is the DFCB sym- 
bol that names the parameter list of the l-form. 

Any E-forK parameter replaces the corresponding parameter in the 
DECB. 

READ — CBSAK) Read a Block (SI 

The READ macro instruction (for BSAil) transmits a block of data from 
an input data set to a aser-soecif led virtual storage area. To allow 
overlap of the I/O operation with processi'-g, the fSID macro irstruction 
returns control to the user's program before the input operation is com- 
plete. (See above for the VISAI! HEAD description.) 

The READ macro instruction may be useci to read backwards from magnet- 
ic tape. 



178 



PageofGC28-2004-6 
Revised 9 May 1979 
By TNL GN20-3941 



Standard form: 



J , 

iame lOperationf Operand 



[ syabol ]|ESAD |decb name^type^dcb address^work area address 

I |[, length] 



and E-form: 



1 1 

Maae | Operation | Operand 

4 1. 

[symbol ] J SEAD | decb name, type, [ deb address], 

f f[work area address ][, length 1,KF= {L 1 1} 



Note: !I!hG name field is reouired with MF=L. If an operand is not spec- 
ifiei with the L-form, it must be specified with the corresponding £- 
form of the macro instruction . 

decb name 

specifies the name to be assigned to the data event control block 
(DECB) constructed as part of the expansion of the macro instruc- 
tion. The DECB is illustrated in Appendix B, Table 13. 

Specified as: One to eight alphameric characters, the first of 
which must be alphabetic; in the E-form only, register 1 may also 
be specified. 

type 

specifies the type of 1EI1> operation. 

Sp ecified as : 

SF - seauential forwar'^ reading of a physical sequential data set. 

SB - seouential backward reading from a itagnetic tape. 

deb address 

specifies the address of the data control block opene*-! for the data 
set being processed . 

Soe cifi el as: In the standard and L-form, as a relocatable expres- 
sion; in the standard and T!-forii, also in register notation (2 
through 12) ; in the E-fora only, as an RX address. 

iiork area address 

specifies the address of an area in virtual storage into which the 
block of lata is to be read. If SP is written in the tyT>e field, 
this operand specifies the address of the first byte of the area; 
if SB is written, the address of the last byte is specified. 



length 

specifies, for fora.at-'J records, the number of bytes to be trans- 
mitted. If this oarameter is specified for format-F or format-V 
records, it is ignored. For format-F and -? blocks, the lenath is 
obtained from the BLFSIZE field of the data control block. This 
operand is reouired for format-0 records- 

Spe cified as: "S* (Mote the apostropiies) , in whicn case the pro- 
grafl attempts to read the maxiaum size specified in the data con- 
trol block (the largest block size that can be specified is 32,767 
bytes) ; as a relocatable expression; in the standard and F-form, 
also in register notation (2 through 12} . 
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Initialization : If this macro instruction is to be executed in a privi- 
leged ikodale, the most recently Issxked.... DCLiSS nacro ir-stroctior. in the 
assembly mast have specified PRIVILEGED (sea Apoendix M) - Alto, the 
address of a save area laust be placed in register 13 before this macro 
instruction is executed, 

C^.UTIOH : ftbnoriRal termination occurs if: 

1. The specified data control bloc^ was not validly onened. 

2. xhe specified D'^.CB is already in use by a previous B'EAD or l;FITE 
macro instruction; that is, it has not been checked by a CHECK 
ffiacro instruction. 

3- An attempt is made to issue a READ macro instruction that causes 

the nuDTiber of unchecked HEAD and WEITE macro instructions to exceed 
the DCBNC? paraneter specified in the data control block. 

4. An attempt is aade to read an OU'rPU'? 5.ata set. 

Pr ogra maina Notes: The READ macro instruction returns control to the 

user's program before the transmission of data has been completed. fo 
determine whether the read operation is completed ^ it is necessary to 
issue the CHECK macro instruction before usina the data transferred into 
the specixied area. The user may deternine when he has reachel the end 
of the last file on the last volume by checking if DCBHW=X»02». A DCBD 
macro instruction oust be included in the orogram and the DSECT 
generated, by the DCBD must be linked to tne data control block,, either 
by loading a base reaister with the address of the DCB and issuing a 
OSIMG statement for the DSECT CHADC3, or by issuing: 

CLI DC5MW~CHADCB+DCB1,X»02» 

This adds the displacement of DCBFW into CHADCB to the address of the 
data control block DCB1. 

After an I/O error, exit is made to the SYSAD exit, if one is speci- 
fied in the DCB, and the 3 sense bytes used to store information Der- 
taining to disk or tape devices are saved in DECB sense bytes through 
7. DECB byte 1 should be set to X'02« to have these bytes put into the 
DECB. (See Appendix B, Table 3.) If no SIMAD exit is specified, 
abnormal termination occurs. 

The DECB employed for a read operation must not be reused or modified 
until the CHECK macro instruction is issued. 

After a READ operation has been checked, the length of a foraat-O 
block or a truncated block in a fixed-length blocked data set can be de- 
termined from the residual count field of the Channel Status Field in 
the DECB. The residual count is subtracted from the block length to de- 
termine the length of block still to be read C^^^ exaaple below) . The 
number of READ ooerations may not exceed that specified in the DCB'ICP 
field in the data control block without using a CHECK macro instruction. 

Example : If the user specifies SYMAD=ERR1 in his DCB and if his DECB is 
named DECBO, the length of the block yet to be read may be determined as 
follows : 
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T tJ 



LI DEC£0 + S7,K •0« IS INCOSRECT LEMGTH I!^DICATOI< SET 

Mil CO:?lTIJ MO^ CO'tTI^DE 

11,DCB-1+4B lES, GET SLOCK LEHGTH 

LH 7^DECB0+3e GET RF3ID0AL COUNT 

SR 11,7 GET BLOCK LENGTH TO BE READ 



A data set: written on a direct access device with track overflow 
specif iesi Bust aave trade overflow specif ie<^ for all read operations 

r-^^ferrina to that lata set. If a track selected by a READ ikacro in- 
struction is flaqqed as defective, the alternate track is automatically 
selected. For any aevxce, the operator is notifiei if intervention is 

recuirei to complete the operation. 

If a FLAD (type SB) macro instruction is issued for a format-V rec- 
ord, the address of the first byte of the record can be calculated by 
subtracting the count field in the charnel status word fron the maxiium 

block size and subtracting the result from the work area address. 

l£ the length specified in the READ macro instruction for format-O 
records is less than the length of the actual physical record, the extra 

byres of -lata are not transmitted. 

The firsi: four bytes on format-^ blocks contain control iBformation 
that is passed with the record when read. The area specified by the 
work area address operand roust be large enough to acconmodate the maxi— 

Eua* record size. 

L- and E -Form D se: The I-form macro instruction results in a macro 
expansion consisting of only a parameter list (DECB) . The forikat of the 

DECB is d.escriDed in Appendix B. 

The E-fornL macro instruction uses the DECn built for it by the L-form 
macro instruction. Any E-form parameter replaces the corresponding pa- 

rairieter in the DECB. 

Ex ample : In EX1, a DECB, with the symbolic name ADECE, is produced as 
part of the in-line expansion- It indicates that forward reading of the 
nert block in the data set associated with data control block INDCB 
should be performed, using area IHAREA- 

EX1 READ ADECB,SF,INDCBA,INAREA 

In example EX2, the type operand indicates backward reaiincr of a 
block of records from the data set associated with the data control 
block INDCb. For foreat-U records, 100 bytes are transmitted; after the 
operation, the bytes extend from INAREA+99 to I^IAREA. For records other 
than format-O, the length parameter is ignored. 

EX2 READ ADECB, SB, INDCB, IHA'^SA-i-99, 100 

! REDTIM — Read Slaosed Real Time (0) 

I The REDTIM macro instruction provides the system time in 
I microseconds. 

f fHame | Operation (Operand \ 

¥ f— 1 \ 

f I [ symbol IfREDTIK | \ 
I i 1 1 

I ^ Qte : There are no operands. 
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I Execution : the Sfstefi/370 (hardware) real tine clock is read (and 
f adjusted) to give the present time in microseconds. 

I R eturn D ata: The resulting double-precision fixed-point number is re- 
I turned in registers and 1 . 

I Example : Suppose you want to find the date and time. You might write: 
f NAHE RIDTIM 



EEL — Release Data Set or Fenove Job Library From Program Library 
List (S) 

The BEL macro instruction may be used to cancel a preceding defini- 
tion for either a public or private data set, or to release the input/ 
output devices associated with a private data set. It may also be used 
to release one or all data sets of a given concatenation, and to remove 
JOBLIB from the user^s i>rogram library list. 

Standard form (see "Operand Strings" in Part II, Section 1) : 

J J 1 J 

|Mame [Operation | Operand 

I 1 ^. 



I ([ symbol ]fREL | {aJ dress of operand string | 

II \ f •data definition name, [data set name]. 
It I I [ (SCPATCHf HOLD} ][ , (SCPATCHIHOLD] ]•} 



L-fora (see "Operand Springs" in Part II, Section I) 



Name | Operation | Ooerand 

h- \— 



symbol | EEL } 'data definition name, [data set name,] \ 

I I [ (SCHATCHf HOLD} ][, {SCRATCH f HOLD} ]»,MF=L | 

I I . I 



Note : A symbol is required in the name field of the L-form. 
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E-form (see "Operand Strings" in Part II, Section 1) : 

I 1 1 

IName (Operation fOperand 

I h-^ 1- 



I |[ symbol ]|HEL | (address of operand string | 

II I I "data definition name ,[ data set name], 
I I I I [ [SCRATCH! HOLD) ],[ (SCRATCH (HOLD} ]•} 
I f I |,WP=(E,list) 

I I I . I 

Si ote : Two positions are supplied for HOLD and SCRATCH so that the user 
I can both scratch the volume and hold the device. 

address of operand string 

specifies the address of the first operand in an operand string. 

Specifie d as; A relocatable expression, or register notation (2 
through 12) . Note that the operand string can also be specified in 
the macro operand as a character string enclosed in apostrophes, as 

shown. 

data definition name 

specifies a data definition name previously issued by a DDEF macro 
instruction or command. This name identifies the data set to be 
released. The name may specify a job library and may also specify 
that the library data set name is to be removed from the program 
library list. 

Spe cified as: A symbol (one to eight alphameric characters, the 
first of which must be alphabetic) . 

data set name 
I specifies the name of one sequential data set in a concatenated 
series. 

Spe cified as: The fully gualified name of a nonpartitioned data 
set or of a nonpartitioned generation of a generation data group 
(identified by absolute generation name or relative generation num- 
ber) - See "Data Set Hame" in Part II, Section 1. 

Default : All data sets concatenated with the named data set are 
released • 

SCEATCH 

St>ecifies that the volume (s) wil l not be re-used by the current 
I task and may be dismounted or made available to other tasks. This 
option is relevant only ilo private volumes. 
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HOLD 



Sp ecif i el as : SCRATCH 

Def ault : See HOLD operand - 

specifies tiiat tne device (s) i^ill be re-used by the current task, 
and i::iiat reservation (s) made by a non-conversational SECURE cop.iianl 
must be retained. 

Spec ified as : a 01 D . 

De f aulr : Defaults are indicated by the action chart below. 

Action chart: for HEL macro: 



I SCHATCH 
-I 



HOLD 



volute disposition 



device disposition 



(1) f SCBATCH 
I 



U) \ 



I SCRITCh 
I 



HOLD 



HOLD 



default according 

to task mode 

logically dismounted 



remains mounted and 

reserved 

logically dismounted 



default according 
to task mode 

released, reservatior 
dropped 

remains available; 
reservation retained 

remains available 
reservation retained 



(1) 
C2) 



default for conversational task 
default for non-conversational task 



Initialization : If this macro instruction is to be executed in a privi- 
leged Eodule, the aost recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M) . Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

CAUT IOH : When a data set has been released, it cannot be referred to 
again until another DDEF macro instruction or command defining that data 
set is issued. 

R eturn Data : After execution of the BEL macro instruction, the low- 
order byte of register 15 contains one of these hexadecimal codes: 

Code Significance 

00 Successful cop.pletion 

04 Defaulted or invalid ddname 

08 Attention interruption occurred 

OC Reserved data definition name specified - not peraitted 

10 Undefined data definition name 

14 Uncataloged on public storage 

18 Undefined data set name 

20 Invalid input 

24 Unable to unload all modules loaded from library 

Ex amples : In KX1, a character constant is given for the data definition 
name DDL In EX2, the address of the same name is given. 



EX1 
EX2 



EEL 

EEL 



»DD1« 
RELTAG 
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RELE'X — Release Read Excl usi ve R ec o r d [E 1_ 

the REL3X macro instruction (for VISAK) ii!akes a record of a shared 
lata set available to otlier users after the record has been read with a 
BEklJ exclusive (type KX) macro instruction. 



I 1 1 

piame f Operation f Operand 



|[BymbGl]IHELEX f deb address 

I I E 



deb address 

specifies the address of the data control block opened for the data 
set being processed - 

Specified a s: Hegister notation (1 through 12) , or an RX address. 

Initialization: If this macro instruction is to be executed in a privi- 
leged aoauler the most recently issued DCLSSS laacro instruction in the 
assembly must have specified FSIVILEGED (see Appendix M) . Also, the 
address of a save area oust be placed in register 13 before this macro 

instruccion is executed. 

CiiOTlOl^ : Exceptional conditions resulting from the execution of a HELEX 
aacro instruction cause control to be passed to the user's synchronous 
error exit (SI)IAD) routine. In this case, the general registers and the 
exceptional condition fields in the lata control block are set as shown 

in Appendixes B and I- . 

P roqraro m inq iote : Rules for sharing VISAP data sets are given in Ipoen- 
dix K. 

EELS E -- Release an Input Buffer (P) 

The RELSE macro instruction (for QSA*') causes the remaining contents 
of the current input buffer to be ignored. The rext GET macro instruc- 
tion will retrieve the first loaical record from the next input block. 

I 1 J 1 

I Same I Operation | Operand | 

I- 1— 1 1 

|[ sYiiibol}|RELSE fdcb address | 
I I I I 

deb address 

specifies the address of the data control block opened for the 
input data set. 

Sp ecified as: Register notation (1 throuqh 12) , or an SX address. 

Init ialization : If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLASS macro instruction is the 
assembly Must have specified PFTVILEGED (see Appendix F) . Also, the 
address of a save area must be placed ±n register 13 before this macro 
instruction is executed. 

CAUilQ S : H RELSS macro instrEction is ignored if used with unblocked 
records, or if all records in a buffer have been processed, or if it im- 
mediately follows another RELSE macro instruction. 
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I BELSE issued before the first GET of the data set is ignored. 

Programmincr Hotes : If a data set is being read backwards, the RELSE 
causes the sane results as in forward reading. 



RBLSEG — Release Reserved Segment Group CO) 

fhe EELSEG macro instruction releases a reserved segment group. The 
name and length are forgotten by the system. Space allocated within the 
reserved secraent group remains addressable. 

Racro-form 



I 1 1 

I Same J Operation | Operand 

I 1 (_. 

|[ syiabol)|EELSSG | B!fAllE=reserved segment name 

I I I . 



RNAME= 

specxfies the eight character EBCDIC naae of an existing reserved 
segment group. 

Spe cified as: Peserved segment nar<e enclosed within apostrophies, 
\ the address of SNAKE is expressed as a relocatable expression, RX 

I address or register notation- If register notation is used, the 

register specified must be the first of a set of paired registers 

containing the reserved segment name. 

De fa ult : K o ne . 

Peturn Data : On return from PILSBG, register 15 will contain a return 
code describing the success of the operation - 

Retu rn Codes 

00 Successful 

Qf^ BMIME invalid 

12 Segment group not available to user class 

kQ System error 

C A P i ION: Any user specified BNA?IE beginning with SIS will be rejected 
by the system. 



Examples: 




1. RL1 


RELSEG 


2. RL2 


PELSEG 


RNH 


DC 


3. RL3 


RELSEG 



RMAfE=»R^IAKF1» 

P!IAMS = RN« 
CL8»3NAF.E» 

RMAKE= (3) 

Execution of example 3 assumes that the reserved segment name is 
contained in reaisters 3 and 4. 

REIBEN — Return to a Program (0) 

f The RETURN macro instruction, when issued in a called program, 

I returns cohileoI to the calling Drogram. Tue functior of this pacro in- 

\ struction depends udob how it is used: 
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1- If the first program to receive control from the sfstem issues a 
RETOSN macro instruction to return control to the system ^ the 
effect is the same as if an EXIT macro instruction had been issued. 

2. h program that follows Type I linkage conventions and is given con- 
trol by the CALL macro instruction ^ can return control to the pro- 
gram that called it by issuing a EBTUTRN macro instruction. 

The HETUSN macro instruction aay also be used to restore the contents 
of the registers of the calling program that were saved by the SAVE 
macro instruction issued in the called program. 

J — _ 1 J ^ 1 

INaMe I Operation I Operand | 

I f 1 J 

I [ symbol JiRETUEN |[ (first register[ ,last register ])][ ,T ][ ,BC=code ] f 

I I I . I 

first register, last register 

specifies the range of registers whose contents are to be restored 
from the save area in the calling program. 

Specified as: The operands are written as decimal numbers such 
that, when inserted in an LE instruction, they cause the contents 
of ^he desired registers in the range from 14 through 12 (that is, 
1^, 15, and through 12) to be restored. 

The contents of registers 14 and 15, if sDecified, are restored 
froB words 4 and 5 of the save area: the contents of registers 
through 12, if specified, are restored from words 6 through 18. 

DexaulT: : If the last register operand is omitted, only the con- 
tents of the register specified by the first reaister operand are 
res-cored- If both operands are omitted, no register contents are 

restored - 

The address of. the save area defined by the calling program must be 
loaded into register 13 before execution of this siacro instruction. 

T 

specifies that a 1 is to be set in the low-order bit of the forward 
link, word 3, in the save area defined by the calling program - 
(See the HARKRTHN macro description.) This action occurs after 
completion of the reaister reloadinq specified by the first 
operand. The bit is set to stop the forward chain. 

This parameter is suppliei to facilitate tracing; that is, checkina 
program flow. There is no tracing in TSS; this parameter is pro- 
vided for compatibility with the IBM OS or OS/VS System. 



2C 



Specified a s: T 

specifies a return code that is to be nlaced in the 12 low-order 

bits of register 15, the return-code reaister. 

ST> ec:ifiei as: Register notation (15 only) , or an absolute expres- 
sion, whose value lies between and 4095 inclusive. 
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I nitiali zati on ; The address of the save area defined by the calling 
program must be loaded into register 13 before execution of this macro 
instruction. 

P rogramming Motes: The contents of register 14, the return register, 
must be restored by means of the first operand of the macro instruction, 
or the register must be correctly loaded before the macro instruction is 
executed . 

The register operands must not specify that the contents of register 
13, the save area register , are to be restored. If the contents of 
register 13 are to be saved and restored, it should be done according to 
the linkage conventions described in Appendix E. The RETURN macro in- 
struction assumes that the save area register (register 13) is correctly 
positioned to the save area defined by the calling program. 

If no return code is specified, the contents of the return code 
register (register 15) will not be changed unless the register operands 
span the return code register. When a RETURN macro instruction ter- 
minates a program, the return code in register 15 can oe interrogated by 
the calling program. 

E xamples : EXI is a REIOEM macro instruction that restores the contents 
of registers 2 through 10. A 1 is placed in the low-order bit of word 3 
in the save area- EX2 restores the contents of registers 14 through 5 
and places a return code of 12 in register 15. EX3 does not restore the 
contents or any register; however> control is returned to the calling 
program. 



EXI 


RETURN 


(2,10) ,T 


EX2 


RETURN 


C14,5),RC = 12 


EX3 


RETUFK 





RSVSEG -- Reserve Segment Gr oud (0 ) 

The RSVSEG macro instruction associates an eight character EBCDIC name 
with a contiguous set of virtual storage segments. A virtual storage 
segment is defined as a contiguous set of sixteen virtual storage 4096 
byte pages aligned on a sixteen page boundary - 

I ll£t£- this macro instruction has one or more operands that can be 
I used only by a systems programmer; these operand (s) are defined and 
I specified in the System Programmer' s Guide manual. 

L -f orm 

, J. ^ «_ — J — _ ^ — ^ ^ — ^ ^ — ^ — ^ ^ — ^ 1 

IName lODeration f Operand \ 

I „+__ ^ 1_-_„^ . ^ ^ ^ , 

fSymbol |RS?SEG | [ RNAKE = , LEIfGTH = , jKF=L | 

I I ^ i ^ . I 

E-form 



I j_ ^ — —.^^ — ^ 

fHaroe f Operation f Operand 



»[symbol ]|RSVSSG f [ RNA?!E = , LEJIGTH = , ADDRESS = , ]KF=(E,list) 

I i ^ I . 



Standard -form 



J J . j__ 

IName fOperation fOperand 

I 1 H • 

f [symbol ]|RS VSEG f [ RNAKE=, LEl!lGTH = , ADDRESS = ] 
I I ^ I 



Note : All operands are keyword. 
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HMAME= 

specifies the eight character EBCDIC name to te assigned to the 

segment group. 

S pecified a s; Name enclosed within apostrophies ; in E or standard 
form only, as the address of RNAKE expressed as a relocatable ex- 
pression, BX address or register notation. If register notation is 
used, the register specified must be the first of a set of paired 
registers containing the reserved segment name- 

Default ; If this operand is omitted, the system will assign a 
unique eight character EBCDIC name to the reserved segment group in 
the form $$$11X11, where XXXXX is from 00000 to 99999. 

CAUTION: RNIMES beginning with $f$ or SYS are reserved for system use 

and cannot be specified by the user. 

LE!iGTH = 

specifies the number of contiguous virtual storage segments to be 
assigned to this segment group. • 

S pecified as; An absolute expression; in the E or standard form 
only, the address of a halfword expressed as a relocatable expres- 
sion, EX address or register notation. If register notation is 
used, the value must be given as a binary number placed in the low 
I order two bytes of the register, right-adjusted. If an expression 

or FX address is used, the address pointed to must be two bytes 
long with the length right-adjusted in the field. 

Def ault ; If this operand is omitted, the system will assign a 
length of one virtual storage segment. 

ADDFESS= 

Specifies the starting address of the virtual storage segment 
group. This address must be segment aligned. 

Specified a s; In the E or standard form only, the address of 
ADDEESS, expressed as a relocatable expression, RX address, or 
register notation. 

Default: If this operand is omitted, the address of the segment 
group will be returned by the system. 

R eturn Data : On return from SSVSEG, all defaulted operands will have 

their system assigned values placed in the NAMESEG parameter list and 
register 15 will contain a return code describing the success of the 

operation. 

Ret urn Code s 

00 Successful 

04 RNAME invalid 

12 Segment not available to user class 

16 Invalid address 

20 Segment group overlap 

24 Invalid length 

32 Insufficient space available 

36 User generated system reserved name 

40 System error or system limit reached 
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Register 1 contains the address of the Haineseg Parameter List. 

n ote : The DSECT, CHANSG covers the Nameseg Parameter List. 

P rogramming Hote s; The return code in register 15 may be used to con- 
struct a branch table to handle the varying results from execution of 
the RSVSEG macro. 

Upon expansion of this macro a set of input flags is constructed in the 
Nameseg Parameter List. They are: 

X»40« RNAME specified 

X«20« ADDRESS specified 

X»08» LENGTH specified 

X«02» RSTRCT=Y specified {system programmers only) 

Upon execution of RSVSEG, a set of output flags will be constructed with 
the above values. 

Subsequent GETHAIN requests which specify the RNAME (user or system 
generated) , will allocate space within the Reserved Segment Group. If 
sufficient space is unavailable within the Reserved Segment Group, no 
attempt will be made to allocate space outside of the Reserved Segment 
Group. Also, GETMAIN requests which do not specify an RNAKE, will not 
allocate space within a Reserved Segment Group. 

L ~ and E-form Use Example 1: 

RLIST RSVSEG LENGTH=2 ,MI=L 

RSVSEG RNAME=R1,ADDRESS=RADD,MF= (E, RLIST) 
R1 DC CL8"MYNAME« 

RADD DC A (X »00i400 000» ) Segment aligned address 

In the expansion of the L-form, a Nameseg Parameter List will be created 
in the following format: 



RLIST — -> 



+ 
+4 
+ 8 
+ 12 
+ 16 
+ 20 
+ 24 
+ 28 



.0 A 


.B 4. 




.0 0, 


.0 2.0 &, 





RNAKE to be filled 

in by S-form 

Not 

used 

Address filled in by E-form 

Not used 



Upon successful execution of the E-form, the Nameseg Parameter List will 
be as follows: 





RLIST^ > 


+ , 
+4 

+ 8 . 


.0 A.B 

. M . 

. r. . 


4. 
Y.N, 

E . 




A . 










+ 12 , 


. 


. a 






Register 


15=0 






+ 16 , 


• .. 


• 






Register 


1=Address 






+ 20 , 


.0 0.0 


4.0 0, 


'o 


0, 


. of RLIST 








+ 24 . 


.0 0.0 


2-6 8, 


.6 


8. 










+ 23 


• 


. 










L- 


and E-form 
RLIST2 


Use Exami 
RSVSI 


>le 2: 


KF=L 












RSVSi 


SG 


MF=(1 


Sr 


rl: 


[ST2) 





The expansion of the L-form will produce a Nameseg Parameter List as 
follows: 
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RLISTz — > 



+ 
+li 
+ 8 
+ 12 
+ 16 
+ 20 
+ 2a 
+28 



A 



B 4 







Upon successful execution of the E-form, the Nameseg Parameter List will 
be as follows: 



ELIST2 — > 



+0 
+4 
+ 8 
+ 12 
+ 16 
+ 20 
+24 
+ 28 



h.B 4. 
X . X . X 



O.S S.0 0.0 
0.0 1.0 0.6 8 



Where < XXXXX < 99999 



fchere X»00» < SS < X»iF» 
< SS < 255 



Eegister 15 = 

Register 1 = Address of RLIST2 

S tanda rd -form Use Example 1; 

ES ES¥SEG 

fhe expansion of the standard-form will produce a Nameseg Parameter List 
as follows: 



CHDXXXXX — > 



+0 


.0 A-B 4. 


+ 4 


. . . 


+ 8 


. . . 



Where CHDXXXXX is an 
assembler generated 
symbol 



+2d ..... 

Upon successful execution of the standard-form, the Nameseg Parameter 

List will be as follows: 



CHDXXXXX — > 



+0 
+4 
+ 8 
+ 12 
+ 16 
+ 20 
+ 24 
+ 28 



A.B 4. 
Y . Y . Y . Y 



O.S S.O 0.0 
0.0 1.0 0.6 8 



ihere < YYYYY < 99999 



Where X«00> < SS < X • FF • 
< SS < 255 



Eegister 15=0 

Register 1 = Address of CHDXXXXX 

If this example were re-entered, the RNAKE field would contain a new 
ENAKE of the form $$$ZZZZZ where YYYYY < ZZZZZ < 99999 and the address 
field would contain a segment address different from that assigned by 
the previous execution. All other fields would remain unchanged. 

S tandard -form Use Example 2: 

RSVSEG RMAME=»SRNM" ,LENGTH=LEM1 ,ADDRESS=ADD1 

ADD1 DS F 
LEN1 DS H 
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The expansioa of the standard-form will oroduce a l?aseseg Parameter List 
as follows: 



■CHDXX7XX — > +0 .0 B.B 4. 

+a . S . R . N . !^ 
+3 .b.b.b.b 



+ 2^ 



.6 S. 



OpoE successful execution of the standard-form, the 'lameseo Parameter 
List Mill be as follows: 



CHDXXXXX — > 



+ . 


.0 11.3 a. 




+ 4 


S . H . H . 


^ 


+ 8 


. b . b . b . 


, b . 


-^12 


> • • i 




+ 16 


• 




+ 20 . 


.0 O.a a.O 


.0 0. 


+ 24 . 


.1 1.1 1.6 8 


.6 3. 


+ 23 


■ • • 





Ifhere aaOOOO is a 
segment address 
previoEsly placed in 
field ABDI & 1111 is 
a length previously 
placed in field LEM1 



CAPTION : Sabseouent executions of this type of example will be unsuc- 
cessful it reserved segment name "SHSH* has not been release-!. 

Standard -form U s e Example 3: 

RLIST3 RSVSEG R^JkKF= •RNF 1 • , J'F^L 

FSVSEG LEWGTH=2,?«F= (E^BLISTB) 

RSVSEG H!*AMF = NEVi^AEE,LEHGTH=LE!0,Mi= (5^ r RH.'^^S) 

IlEWRJAKii DC CL3»KY»ARi:2" 

LBN 3 DC HM6» 

fhe expansion of the L-foriL will produce a ^iameseg Parameter List as 
follows: 



RLIST3 — > 



+0 .0 A.B 4. 

+ 4 . R . Jl . I! . 1 

+8 -b-b.b-b 



+ 24 . 
+ 28 . 



.4 0. 



Upon successful execution of the first E-form, the list will be as 
follows : 



ItLlSi3 — > 



+0 
+ 4 
+ 3 
+ 12 
+ 16 
+ 20 
+ 24 
+ 28 



A.B 4. 
R . N . M 
b - b . b 



O.S S.O 
0.0 2.4 8 




5 8 



X»00» < SS < x'ff* 



Opon successful execution of the second E-form, the list will be as 
follows: 
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^.LISIS — > 



+ 


.0 A.a 4. 


+4 , 


. M . Y - H . A . 


+ 8 


. H . E . 2 . b . 


+ 12 


• • • • 


+ 16 


> • • • • 


+ 20 


.0 O.t t.O 0.0 0. 


+ 24 


.0 0.1 0.4 i3-6 3. 


+ 2S 


> • • • • 



Where tt ^ 35 and 
X'OO" < tt < X'FF' 



Note: If the second E-fom hai not specified a new ESAHE, the system 
wouli have passed a return code of four in register 15 and no changes 
woali have been aaie to the !JaFieseg Parameter List- 

SA £C — Speci fy Asyn chro noti s Entr y C onditio ns (S) 

The SKijC macro instruction creates an interruBt control block (ICB) 
to service asynchronous interruptions, and specifies the address of a 
communication area, the data control block associated with the device 
the user desires to service, and the interruption handling routine's 
entry |*uint. 

L-f orE: 




Operand 



[EF={entry point address|0}] 

[ , CDCB=dcb address! SDA=sda address}] 

[ ,COaAPF%=area address] 

[ ,{INTTYPfllTT^TYP} = {C ( {A | S | B} ,code[ ,-.-]) 

f IIULLfSAVEIEESTORE] ] 
[ ,PFKHSK= {(11 1 SIP} , {integer I integer-integer}) 

I BULL I SAVE f RESTORE} ] 
[ ,FF={L| (£,icb address)}] 



Mote : There is no standard form of this macro instruction. The name 
field becoiRes the ICB address used by a SIE or DIE macro instruction. 



fip^ 



specifies the entry point of the interruption routine to which con- 
trol is to be transferred when an interruption of the type speci- 
fied by ISTTY? occurs. The routine must be aligned on a fullword 
boundary. 

Specified as : 0, or a symbol (one to eight alphameric characters , 
the first of which must be alphabetic) . 

Default : 0. If this operand is omitted, or if FP=0 is specified, 
the user sust place the entry point name of the ii>terruption rou- 
tine in the interrupt control block generated by this macro 
instruction. 



DC5= 



specifies the address of a previously otsened data control Hock as- 
sociated with the device or unit for which the routine is to serv- 
ice interruptions. If the SYSIN terminal is specified, the DCB pa- 
rameter must be specified as SYSIjIDCB, and the OS ATT macro 
instruction parameter must be specified to disable the higher 
priority system-supplied attention interruption routine for the 
SYSIH device. 

Specified as: In the L-fora, as a relocatable expression; in the 
F-form, as an RX address or as register notation (2 through 12) . 
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specifies the address of a halfword containing the SDA (Symbolic 
Device Address) of the device whose interruptions are to be ser- 
viced by this routine- If a SYSIN terminal is specified, the SDA 
parameter must be specified as SYSINSDA, and the USATl macro in- 
struction must be specified to disable the higher priority systeia- 
supplied attention interruption routine for the SYSIN device. 

Specified as ; In the L-f orm , as a relocatable expression; in the 
I 1-form, as an RX address or as register notation (2 through 12) . 

COMAEEI= 

specifies the address of 16-byte area in main storage, aligned on a 
fullword boundary, that is to be used by the control proaram to 
pass interruption information to the interruption routine. 

Specified as: In the L-fom, as a relocaxable expression: in the 
I E-form,. as an RX address or as register notation (2 through 12) . 

I I!ITTrP=/A1TNTYT = 

specifies types of interruptions that will cause entry to the in- 
I terruption routine, the treatment of the interruption informatior 
I specified by the code operand, or any action to be taken. IITTYP 
I is the preferred keyword to use for new code; ITTHTYP is accepted 
I so that older programs using this keyword need not be receded - 

Specified as ; 

k - specifies that the interruotion information (code) is to be 
I added to the existing IMTTY^/ATTHTY^ field of the ICB. 

S - s|>ecifies that the interruption information (coie) is to be 
I subtracted from the existing I!I1TYP/ATTNTYP field of the ICB. 

B - specifies that the interruption information (code) is to 
f replace the existing HitTTYP/AlTWTTP field of the ICB. 

\ code - specifies the type or types of interruptions to be added 

I to, subtracted from, or replaced in the HiTTIP/lTTMTY^ 

\ field of the ICB, and can be written as one or more of rhe 

I following: 

AT1!M - inaicates an attention interruption. 

CANCEL - indicates that the routine is to service interruptions 

from the CA!iCEL key on the alTjhai\eric keyboard. Ihe C.^'i- 
CSL key should be reserved to request control program 
intervention . 
ALL - indicates that the routine is* to service interruptions 

from all sources. 
EOS - indicates that the routine is to service interruptions 

caused by execution of enc'-of -order-seouence orders , 
AE - indicates that the roc tire is to service interruptions 
caused by asynchronous errors. 
f EHD - indicates that the routine is to service interruption^^ 
I iroifl the ^i^D key on a 225C. 

f LP - indicates that the routine is to service interrutions frcn 
I the light pen on a 3270 or 2250. 

I KULL - inaicates that none oi the types of interrut>tions coverei 
f ty I^TiTYr/ATTNTY? are to be service'.. 

I SA¥E - specifies that the contents of the IM't^'^IP/AT'T'ijti-? ii<=ld 
of the ICE are to be saved. If this or NULL or E'^STOEE 
is written, the A, S, or t and interruption- tyoe codes 
are not written. 
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RESTORE - specifies that the contents of the IMTTYP/ATTHTTF field 
of the ICB are to be replaced with the mask saved by an 
INTTYP=SAVE operand in a previous SAEC macro instruction. 

PFKMSK= (3270, 3066, 2250 devices only) 

specifies the program function key (s) f roB which asynchronous 
interrupts are to be serviced by the interrupt routine, or changes 
the program function keys to be so serviced, or permits the over- 
riding of presently defined program function keys with those de- 
fined in a previous SAEC macro. 

Spe cified as : 

{AtSfr;} ~ sic«ecifies that the prograc function key (s) that follow 
(integex) are to be added to, ^^ubtracted from, or replace those 
already specified in the PPKMSK field of the ICB. 

integer - identifies the proaram key numbers to be added, sub- 
tracted, or replaced; one or more decimal digits separated by com- 
mas in the range to 31 • to specify a consecutive range of program 
function keys, code the first and last key numbers separated by a 
hyphen; for example, 7-11, 

NULL - specifies that the interrupt routine is not to service 
interrupts from proaram function keys. 

SA¥E - specifies that the current PPKMSK field of the ICB is to 
ba saved. 

EESl'OES - specifies that the current PPKMSK field of the ICB is to 
be replaced ^ith that of the last SAEC macro instruction 
having a PFKWSK=SAVE operand. 

M^e: if HULL, SAVE, or RESTORE is coded. A, S, or R and integer 

are not coded. 

icb address 

specxfies the address of the interrupt control block. 

Sp e cified a s: Pegister notation (1 through 12) , or an BX address. 

CAO T IOtI : if an interraption routine is to serve multiple units, a 
separate ICB roust be defined (SAEC aacro instruction) and specified (SIR 
macro instruction) for each unit; also, the routine must be reenterable. 

Prograiaminq Hotes: Ihe data control, block address or SDA address in an 
ICB should not be changed whil-3 the associated routine is active (cur- 
rently processing or interrupted before coruPletion of its processing) 

without first deleting the interruption routine with a DIE macro in- 
struction. After changing the DCB/SDA address, the routine must be re- 
established witii a SIP macro instruction - 

The foriLat of the first four words of the interrupt control block is: 

J 1 

ICh +0 f COMABEA ADDR | 

h » 

+4 I DCB or SBA ADDS | 

^ -I 

+a I PFKHSK I 

F 4 



I +12 I I!iTTIP/ATTKTyP 
I I 
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Uxjou enrry to an interruot-ion routine^ reaister 1 contains the ICB 
address and the COM,AREA contains the inf oritatioii relating to the inter- 
ruption to be serviced. Trie format of the comniiinication area is: 



COFAREA +0 

+4 

+8 

+ 12 



1 1 1 

1 X«03" 1 OVERLAl f ^?F 
I 1 1 


KEY 


1 1 

!^0. fI!lTTY^/ATTNlY?f 
.._.. J. _ . _ __.. ._ 1 


f SE^Si. DMA \ 


1 X POSITION I 
1 1 




1 

I POSIIIOH 1 
1 


1 f 

1 RESLE¥ED f 

1 „ , ,. , , , . 1 



liJTrYP/ATT^STYP 

indicates the type of interruption that occurrexl ^ as 
follows : 

Code Type 

01 EHD key (2250) 

02 Procrram function key (2250, 3270, 3C66) 

03 Liqht pen (2250, 3270) 

04 lEOS (end-of-sequence) {2?50) 

05 CAMCn or ATTEM (ALI) 

06 AE (asynchronous error) (2250) 

07 Sense operation failed (2250) 
03 REl operation failed (2250) 



and E-Porm Ose: If neither 



nor "S-form is specified, L is assumed. 



The in-line code for the F-form alters the contents of an ICB. There- 
fore the f!P operand, with no other operands is meaningless and produces 
an asseably error message. 

The A, S, R, SA?E, and RESTORE operands are specified only in the 
B-form of this macro instruction. 

I Exampl es : the ICB may be referred to by the symbolic naike ICBTI. Con- 
I ditions are defined for an interruption routine whose initial entry 

point is the location specified by the synliolic nane AE 1 . All interrup- 
tions are processed by this- interruptioii routine. 'when an interruption 
on the device specified by the DCB operand GPAPHD1 causes entry to ftBl, 
the interruption data is present in the first four words of ARFA1; the 
address of the ICB is in reaister 1. 



ICbXI SAEC E?=AI' 1 ,DCB = GI: APHD1 , INTTYP = 
COMARFA=AREA 1 ,MF=L 
bS OF 

AREA1 DS CL16 



(ALL) 



f If the user wishes to have a routine called whenever PF key 3 on the 
I terminal is pressed, the user could code: 



I 



SAEC EP=RlNl,SDA=SYSIHSDA,C0MAEEA=C0K,PFKaSK=3 



I Then, whenever PF key 3 is pressed and the user has released the key 

I from the access method (see Device Screen Commands in the Terminal 

I Oser's Guide ) , the routine will be called asynchronously at entry RTI1 . 

SAI — Save and Inhibit [01 

The SAI macro instruction saves the inhibit status of the task moni- 
tor and sets the problem program in the inhibit state. SAI does not 
handle the inhibit status for program or SVC interruptions for user- 
defined interruption handling routines. 
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I 1 1 

IKaEie fODeration f Operand 

I 4__ 1 



I [ syiibol ]| sm |[ address of status area] I 

I 1 1 1 

address of st-anus area 

Fpeciiies a one-byte area for savirg the Drier inhibit status of 
the task monitor. 

Spec ifie d as: Tegister notation (2 thro'jah 12) , or a relocatable 

expression . 

Defauxt: The probleii urogram is set in the inhibit state. 

Initialization : If this macro instriiction is to be executed in a privi- 

leaed moiule, the cost recently issued DCLASS macro instruction in the 
assembly mast have soecitied PRIVIIFGFI (see Appendix K) . Also, the 
address of a save area Fiust be placed in register 13 before this macro 
instruction is executed. 

Proqramrainq !lotes: The task rionitor always dispatches privileged rou- 
tines in the inhibit state, unless the interruption program was made a- 
vailable to the system by a SIV. macro instruction with the operand 

I5IHIi;IT^>TiJ- 

The task monitor disoatches to nonprivileqed interruption programs in 
the enabled state, unless the interruption program was made available to 
the system by a SIR aiacro instruction with the operand I1IEIBIT=YES. 

I Tnere are separate inhibit indicators for Privileged and nonprivi- 
I leged prograiSiS . ihe SJkl macro instruction sets the appropriate indica- 
I tor according to the attributes of the program being assembled. A non- 
l privileged program cannot inhibit dispatchinq of privileged programs. 

S AVE — Save Register Co n tents (0 ) 

The SA¥E macro instruction is normally written at each entry point of 
a called proaram. Upon entry to the program, SA¥E stores the contents 
of specified registers in a save area orovided by the calling program. 
The saved register contents may then be restored by a RETURN Macro in- 
struction, an LK instruction, or other proaramming technique. 



JMame | Operation I Operand 



r[ symbol ] f SAVE | (first register[ ,last reaister ])[ ,T }[, identifier ] 

I i I 



first register , last register 

specify the range of registers whose contents are to be stored in 
the save area defined by tbe calling program that is pointed to by 
register 13. 

Sp ecified a s: The operands are written as unsigned decimal numbers 
or absolute expressions so that, when inserted in an asseabler lan- 
guage STM instruction, they cause the contents of the desired regi- 
sters in the range of 1^ through 12 (that is, m, 15, and through 
12) to be stored. The contents of register 14 and 15, if speci- 
fied, are saved in words 4 and 5 of the save area; the contents of 
reaisters through 12, if specified, are saved in words 6 through 
13. The contents of a given register are always saved in a partic- 
ular word in the save area- ^or example, the contents of register 
3 are always saved in word 9 of the save area, even if the contents 
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of register 2 are not saved. The register operands aust not re- 
quest saving the contents of register 13, which is the pointer to 
the save area. 

Def aiklt ; If the last register operand is omitted , only the con- 
tents of the register specified by the first register operand are 
saved. 

note : T and identifier are parameters used to facilitate tracing; that 
is, checking program flov. There is no tracing in TSS; these parameters 
are provided for compatibility with the IBM OS and OS/VS Systems. 

T 

specifies that the contents of registers 14 and 15 are to be saved 
in words 4 and 5 of the save area, if not already saved by the 
register operands. If the T and last register operands are present 
and the the first register operanc? is 14, 15, 0, 1, or 2, the con- 
tents of all registers from 14 through the last register value are 
saved. 

identifier 

specifies the identifier of the entry point at which the SI?E macro 
instruction is located. 

Sp ecified a s; A character string or an asterisk (*) . If a 
character string is specified, it may consist of as many as 255 
characters; it aust contain no blanks or commas. Because it can 
have a lengtih greater than eiqht characters, the operand can be a 
combination of a data set name and a program name, or some other 
complex name. 
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If this operand is written as an asterisk^ the entry -point identi- 
fier is the same as the sfnibol in the name field of this macro in- 
struction. If the name field is blanks the name of the control 
section containing the SAVE macro instruction is used. 

Pr ocrraEt m inq Mote s; If the called routine is to use register 13^ it must 
save the contents of register 13 and, before termination, restore it. 
The SAVE macro instruction must not be used for this saving. 

yhen the macro is expanded, both the entry-point identifier and the 
count of the number of bytes in the identifier, in that order, are 
placed in front of the actual entry point to the SAVE routine. The 
entry point identifier is assembled starting at the nearest possible 
halfMori boundary preceding the actual entry point. Because the count 
byte always immediately precedes the entry point, an extra byte is some- 
times needed to achieve the reguired halfword alignment for the identi- 
fier string. When the extra byte is needed, a character blank is 
inserted at the end of the entry point identifier, immediately preceding 
the count byte. The count byte contains a count equal to the number of 
characters in the identifier plus the blank (if used) . The count byte 
itself is not included in the count. 

A symbol in the name field of a S?VE macro instruction is an entry- 
point name. The entry-point name and the entry-point identifier are the 
same only if the last operand of the macro instruction is an asterisk. 
The entry-point name is used in passing control ro the entry point- If 
a program in another assembly module is to branch to the entry point, 
the entry-ooint name should be an operand of an assembler-language FMTRl 
statement provided by the user in the current asserably module - 

Examples : EXl saves the contents of registers 14 through 10. The con- 
tents of registers 1U and 15 (and registers and 1) are saved because 
the 1 operand is written. The entry point identifier is FitBT!IA7B99. 
EX2 saves registers 3 and 4. The entry point identifier is BX2. 



Examples 



Macro Expansions 



•:X1 SAVE (2,10) ,T,F4rTNA7B99 



'hl2 SAVE (3,4) ,,' 



EX1 



EX. 



DC 
DC 

STM 

DC 
DC 

STr 



OH 

CL 11 « F4RTJJ A7B9 9 • , FL 1 » 1 1 » 

14,10,12(13) 

OH 

CL3»EX2» ,FL1»3» 

3,4,32(13) 



SEEC — S pec ify Ex^e rpa l E ntr^^ Conditio ns (S) 

The SEEC inacrc instruction creates an interrupt control block (ICB) 
to service external interruotions , and Eoecifies the address of a commu- 

nicatioii area and the interruption handling routine's entry point. 



and 



>art 2: 
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1 1 

Name [Operation fOperani 



[ symbol jlSEEC f[SP=eiitry ooint ][ ,CD^AVE-^=area a^iliress ] | 

I »i ,IfTTYP=raessaae number ][, FSGAREA^buffer addresr 1 | 

I |[ ,aSGLTK=leRgth of messaqa ][ ttSGHDP= {Y | K} ] » 

f |[ ,MF={L| (E,icb a?«dress)} ] \ 

I 1 1 1 

lote: A syaiboi is racuirei in the name field with the L-fora and 

becomes rhe ICB address used by a SIF or DIP macro instruction. If the 
!1F operand is omitted, !iF=L is assuined. There is no standar."^ forir» cl 
this macro instruction. 



v:i>= 



2P= 

specifies the entry Doint of the interruption routine to vhich con- 
trol is to be transferred when an interruption occurs for the Mes- 
sage specified by INTTYP. 

Spec ified as: 0, or a syibol {one to eiaht alphameric characters, 
the first of which is alphabetic) . 

Default: G 

If this operand is omittei or if EP=0 is specified, the ^ser must 
place the eni:ry-point name of the interruption routine in the 
interrupt control bloclc generated by this macro instruction. 

COMIkEEIk = 

specifies the address of an area in main storaae, alioned on a 

fullword boundary, that is to be used by the control program to 

pass interruption information to the interruption routine. 

Specified a s: A relocatable expression; in the E-fcra only, as an 
SX address, or register notation (? through 12) . 

IHTTY?= 

specifies the message number {0-2SS) that will cause entry to the 
interruption routine. 

Specified as : A namber, maximum 255. Pessage numbers to 127 are 
reserved for nonprivilegei programs, Ressage numbers 128 to 236 are 
reserved for IBf privileged programs, and messace numters 237 to 
255 are reserved for installation privileged proarams. 

rjSGAEEA = 

specifies the address of an area into which the messagct is to be 
laoved. Tne message header precedes the message text if HSGRDF^Y is 
specified. 

Specified as : A reloca.table expression; in the E~forrc only, as an 
EX address, or register notation (? through 12). 

KSGHDR= 

specifies whether the entire Messaoe Control Blocli: (KCB) , the mes- 
sage header and the text, is to be moved into the message area, or 
3ust the message text. If the user wants header information, he 
specifies ?!SGIIDP=Y and must make the message area (specified by the 
MSGAREA operand) two doublewords longer than the length for the 
message specified by FSGLTH. The header will be placed in the mes- 
sage area ahead of the text. 

Specified as : 

I - the message header is to be placed in the message area as well 
as the text. If interruptions are received via I*fTI!IO only 
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(prograra is in disabled state) r Y should be specified. 
N - only the messaqe text is placed in the messaoe area. 

De i_a ult. : N 

I1SG1TH = 

SDeciiies the length in doublevords of the message. 

Speci-^ied as : A number ^ taxiiiim 255. 

icb address 

specifies the aidress of the interrapt control block. 

Specified a s: Kn 31 address, or register notation (1 through 12) . 

CAUTIO N : If an interruptioB routine is to serve multiple messages, a 
separate ICB rausi: be vlefinel (SKEC macro instruction) and specified (SIR 
macro instruction) for each messaae, and the routine must be 
reenterable. 

Progra atkina Sotes: The message number (INTTYP) in an ICB should not be 
changed while the associated routine is active (currently processing or 
iriterrui»ted before completion of its processing) without first deleting 
the interruotion routine with a DIE macro instruction. After changing 
the IMITIP, the routine must be reestablished with a SIB macro 
instruction . 

if an external interruption occurs and no routine has been created by 
a SIF eacro instruction to handle the iriterruption, a ™essage is sent to 
the terminal indicatina that the interruption has occurred but no rou- 
tine is available to handle the interruot ion. This occurs for all mes- 
sage numbers except 127, for which no indication is nade. 

ILe forniat of the first three words of the interrupt control block 



ICB 



-1-0 



+ i+ 



+ 3 



+ 16 



f co?:afei iddpess i 


1 RESE2¥rD \ 


\ EESSRVED I 

1 . 1 


\ EHTHY POIMT 


ADDRESS r 



Upon entry to an interruption routine, register 1 contains the ICB 
address and the COMUBEI contains the information relating to the inter- 
ruption to be serviced. The forraat of the communication area is: 



COMAREA +0 

-i-8 
+ 12 



I 


X»02» 


'1 1 
[ MESSAGE LENGTH [ 

4 , ., 1 


MESSAGE NOMBFF 








MESSAGE AREA 


ADDRESS 




1 SBSEHVED 1 






RESERVED 




1 

1 

1 



R eturn Data : When MSGHDR=I is specified, the message (header and text) 

is placed in the message area by the SEEC macro instruction, the address 

of the first byte of the message header is placed in the KSGIBEI address 

field of the COHAEEA, aad the length of the message text in doublewords 
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is placed in the WSGLTH field of the COMAREI. When MSGHDE=I is speci- 
fied, the message area contains: 

Offset Content s 

Length of nessage text in donblewords (1 byte) 

3 ffessaqe Code (1 byte) 

4 ¥SEBD SYC (2 bytes) 

8 Identification of sending task (2 bytes) 
Id Identification of receiving task (2 bytes) 
16 Message text starts. 

When MSGHDR=H is specified, only the messaae text is placed in the mes- 
sage area, starring at byte 16. 

If KSGHDR=Y is specified ani the niessage is truncated, the truncated 
length is placed in the COri^HEA length field; the header is always 
passed. 

L - and E -For m Use: There is no standard forE of this macro inrtruction, 
since no linkage is performed- The in-line code for the E-form alters 
the contents of an ICB. Therefore, the !!i operand ¥ith no other 
operands is meaningless and produces an assembly error message - 

E xampl es: 1) The ICB may be referred to by the syiabolic nane ICBEl. 
Conditions are defined for an interruption routine whose initial entry 
point is the location specified by the symbolic name PE0G1 . When an in- 
terruDtion for messaae #^ (as soecified by the IMTTY^ operand) causes 
entry to PE0G1, the interruption data is in the first four ^oris of 
AREAl, and the address of the ICB is in register 1- 

ICBE1 SEEC SP=?FOGl,IlTTyP=-4,COK]lREI=iSERl,rSG]lREA=-iHEl2, 
:4SGLTH=72,MP=L 
D5 Of 

IREAl BS C116 

APS»2 DS 72D 

2) This macro instruction will, when executed, cause the ICB dc-finei in 

example 1 to be modified, allowina interruptions for message #6 (but no 

longer for message *6) to be T>rocessed by the routire with entry point 
at PROGl. 

SEEC IJTTIP=6,»»F=(E,IC3E1) 



\ S ETD¥ — Set Diction ary Value (0) 

The SE'£D¥ macro instruction allo-js a user application progran to 
define, Eanipulate, and delete TSS Dictionary values (entries) . 

Note : The SETD¥ macro plus the GgTDV macro give the proarammer 

capability of creating, updating and deleting en trices in the TSS 
Dictionary . 

I 1 1 ^ ^ ^ I 

I lame | ODer at ion f Operand f 

!_ ,_ ^^ 1 

I |SSTD¥ I [symbol, type, value] ,-- . f 

I I I i 

symbol 

nawe of the dicxionary entry or value xo be ser. 

Specifi ed as: one-to-eight characters in sinole ouotes, the first 
character of ¥hich irufx be alphabetic, or an RX a-"' dress. 
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aote: if given as an EX address, the address roust be preceded by a 
one-byte length. 

type 

indicates the typ»e of entry. 

Specified a s: any one of the following: 

■SYN" - synonym 

•DEB » - default 

•lilTG* - integer comnand symbol vord 

•CHIiR" - character coEmani symbol word 

•FLT» - floating point number 

•LOG* - logical command symbol word 

■HEX» - hexadecimal command symbol word 

Rules concerning type are as follows: 

(1) •CHAP." and »HEX» must be less than 2S6 bytes in length. 

(2) "INTG" and •HEX' must L3 on a fullword boundary; a length of 
four is assumed. 

Default: none 

value 

the ne# value to be given to the dictionary entry defined by the 
symbol and type parameters. 

Sp ecir iec as: ar RX address ^ a character string, or register nota- 
tion {z through 12) . 

Dei a 'lit: : if value is rot given, the dictionary entry defined by 

symbol and type will be deleted. 

Initializ atio E : If this uacro instruction is to be executes in a privi- 
leged Module, the most recently issued DClliSS macro instruction in the 
assembly mast have specifier PRIVILEGED (see Appendix M) . Also, the 

address of a save area must be placed in register 13 before this macro 
insTirucrion is executed. 

CAUx^o a : 'Ihere is no validity checking by the SETDV procesFor to :iake 
certain that the value given conforms to the »type» co.^, e specified. 



Example 1 : 



LA S3, SYMBOL 1 
SFTDV { (R3) , »It%^T^i • ,RC4) set. return code for user 



DC AL1 CL»SYH30L1]| 
SYEBOLI LC C»SYSRC» 



I J. E.3,5C0 
..lTDV ('SYSFC* , 'lyi^^*, CF3) ) 



D:_: f •(}' 
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SBTL — Specify Start of Segaeatial Processing (Rl 

The S^TL Aacro iastruction (for VSJIH, ?ISJIM, and QSAM) positions a 
data set to the beginning ^ end, previous record, or any point within the 
data set. 



I 1 1 

llaae | Operation! Operand 

I , , 

|[syittbol]lSETL |dcb address ^processing type[ , record key] 



deb address 

specifies the address of the data control block opened for the data 
set being processed. 

I Specified as ; Register notation (1 through 12) , or an RX address. 

I processing type 

I specifies the starting point for processing and any optional serv- 

I ices requested. 



200.2 



letura Data : Eegister 15 is set to 08 ^ meamiiig noraal return 

SEggP — Set Pser Timer cm 

Tlie SlTffl sacro instruction sets tlie user tiaer field in the ITSI, 
thereby limiting four task's execution time. 



I 1 "1 

(lane (Operation! Operand 

I 1 ^-1 ^ 

I [ symbol ] | SI TTU | [ time ] 
I 1 -I 



time 

specifies the time duration in milliseconds that fou want placed in 
the user timer field. 

Specified as s 1 decimal number from to 55361812 or^ if the num- 
ber is first placed in a register, in register notation (1 through 
12) . 

Default : It is assumed that the issuer has placed the time dura- 
tion in register 1. 

Initialization ; I BCLASS macxo instrnction with the FEIflLBGlD option 
must be coded in a CSSCf prior to coding SETTWm If more than one DCllSS 
macxo instrnction is issned in a module, the last DCl^SS issued prior to 
coding SlfTO must be issned with the FlIFlLBeEB option. 

Execution: The guantity contained in register 1 is converted to micro- 
seconds and stored in the extended task status index field called user 
timer value (XTSOTI) . 

Example : Issume that register 5 contains the number of milliseconds to 
which you»d like to set the user timer. Tou might write: 

HAIE SETTIJ C5) 

SETUP — Set gp Task Status Index Field fB) 

The SETUF macro instrucrtion permits you to alter or set the contents 
of a selected field in the TSI. 



I 1 -I 

IHame (Operation (Operand 
-( ^-1- 



([ symbol ]( SB TO F ([ field ][ ^register] 



field 

specifies the field you want to set or alter. 

Specified as : One of the codes described below, or, if a value 
€:orresponding to one of the codes (also shown below) is first 
placed in register 15, as (15) . 

USEEID - set the user identification field 
S7SI1 — set the input data set location field 
SYS OUT - set the output data set location field 
SOFlIf - operator/ (combined with privilege class-E) 

syst€)m programmer privilege 
SFFII? - system programmer, non privileged 
IFEI? - user 
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COI¥ ~ set the conversational tasl: flag 

ITIFLG - set the intertask message flag 

IFR - set the external priority flag 

lUTH - set the privilege field 

MIV -» set the maxiana aaxiliarf storage fieM 



Field 



Value 



USEMD 


1 


SISIM 


3 


SISOOT 


4 


SOPRIf 


6 


SPPKI? 


7 


0P1I¥ 


9 


COM? 


10 


ITMFLG 


12 


IPH 


13 


lOTH 


1% 


HI¥ 


16 



register 

designates the even-odd register pair in which foii have placed the 
information fom want put into the specified TSI field* 

Specified as : The odd register ,► expressed as am absolute expres- 
sion or register notation. 

Initialization : I DCLISS macro instruction with the PlIflLBGlD option 
must be coded in a CSECT prior to «>ding SETUP. If more than one BCLISS 
macro instruction is issued in a module, the last DCllSS issued prior to 
coding SE!PIIP must be issued with the PHIVILEGEB option. 

Execution: From one to eight bftes of registers and 1 are inserted 

into the task status index field specified bj the low-order bfte of 
register 15. The number of bftes to be inserted depends on the field 
specified. 

Field Code Implied length fbvtesl 



OSESID 

SYSIl 

SISOUT 

SOPRIf 

SPPRIf 

UPRIf 

COM¥ 

ITIFLG 

XPR 

lUTH 



1 

3 

i» 

6 

7 

9 

10 

12 

13 

111 

16 



8 

2 
2 



2 
1 
2 



Example ; Issuae that registers 12 and 13 contain an eight-character 
user identification. lou might write: 



TEST 



SETUP 



USEHIB, (13) 



SETPR — Set Up Pnit Record Device fBI 

The SBTUR m.a€rro instruction specifies the configuration for online 

printers and card punches. 
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-I 1 ^ 

I Operation | Operand 

-I ^- 



IWaae 
I- 



I |[syiibol]|SET!Il 

I ■ 



I £dcb address[ ,setup]| parameter 



deb address 

specifies the address of the data control block opened for process- 
ing a data set on a printer or card punch. 

Specified as ; A relocatable expression or register notation. 

Default : Mone 

setnp 

specifies the address of the desired fora nnaber for the punch. 
For printers, it specifies the naae of the default region in the 
SYSOCS data set from which all printer defaults (FCB, CHIIl/TRJIIM, 
etc.) aaf be found. 

Specified as : one to six alphaneric characters 

Default : PIPEl. 

parage ter pointer 

specifies the address of a parameter list (which is defined by the 
CHASOl DSICT) which contains the exact specifications for a printer 
setup. This parameter list is in the following format: 



IBDR OF ISII DCB 

SfAlf OF CHIIS fO LOAD 

BEG HIEB OF 1ST CAT EMTBl 

RBG MIHE OF 21D CAT BlTRf 

SSG NAME OF 3 ID CAT EMTIT 

HSG MARE OF 4TH CAT ElTRf 

FCB REG NAME TO LOAD BY 

FQI OF SYSOCS DS TO USB FOB LOAD 

FQa OF COPY HOD DS 

Y! FOB BTS 

PAPER TO USE ** NET ** 

iO COPIES OF DS 

NO COPIES OF PAGE (OILY 1ST BYTE USED) 

NAME OF FLASH IMAGE 

COUNT OF COPIES TO FLASH 

NAME OF DEFAULT REGION IN DCS 

¥ID THIS JOB 

FLAG BYTE 

0=FLASH MAY OR MAY NOT BE RBQD 

1=D0 NOT FLASH 

0=CHARS PABH FILLED IN BY PRINT CilD 

1=CHARS FILLED IN VIA DEFAULT 

ITERS ION ID OF COPY MOD DS 

CURRENTLY USED LENGTH 

USED FOE ALIGNMENT fSPARE) 
USED FOR ALIGlffBxfT (SPARE) 
LSI OF TABLE 



To ensure a valid setup, the SETUR macro instruction 
should be issued before any I/O operations are directed to a printer or 
punch. This is donci by issuing SETUR immediately after opening a data 
set or after the FINISH macro instruction is executed and the I/O opera- 
tion ccwpleted. 



SUE ORG 


DS 


OF 


SURDCB 


DS 


A 


S OR CHARS 


DS 


OC 


SURCHAS1 


DS 


CL6 


SURCHAR2 


BS 


CL6 


S0RCaAR3 


DS 


CL6 


SURCHAR4 


DS 


CL6 


SURFCB 


J>S 


CL6 


SyiDSN 


DS 


CL44 


SURCPDSN 


DS 


CL44 


SURBURST 


DS 


CL1 


SORPlfER 


DS 


CLIO 


SURCOPYG 


DS 


X 


SUICOPY 


DS 


XLS 


S OR FLASH 


BS 


CL8 


SURFCNT 


DS 


X 


SURFORH 


DS 


CL6 


SURVID 


ns 


CL6 


SURFLG 


DS 


X 


SDRFLSH 


EQU 


SURFLG 


SORFLSHl 


EQU 


X»80« 


SURDFLT 


EQU 


SURFLG 


SURDFLTM 


EQU 


X»40« 


S0R¥ID2 


DS 


CL6 


S UR LEND 


EQU 


* 


SURL 


EQU 


*-€HASUE 




DS 


2X 




DS 


21F 


SURLEM 


EQU 


♦-CHASUE 


Procrrammina Notes: 


To ensur 
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Card Punch s The setup for a card piuicli is described by the form utiiiiber 
of the card that the operator is to load into the pimch-feed hopper of 

I the punchy This form nuaber is an installation -defined constant. When 
the macro instruction is exescuted, the SETOfi routine determines which 
form is mounted in the punch (the currently mounted form number — or 
zeros if the DCB was Just opened — is stored for each device in the 
SDITJ m If the desired form is already mounted, control is returned to 
the invoking routine with a return code of 0. If the form is not 
mountedp^ a message is written to the operator (ITO) to mount the desired 

I form number (6-byte parameter) , and to ready the punch. A return code 
of 4 is provided to the calling task. When the operator indicates that 
the punch is properly loaded, by causing a not-ready to ready interrup- 
tion, the SDIT is changed to reflect the new form number. On the next 
call to SlfUE, control is returned to the invoking routine with a return 
code of 0. 

I Printer : if the •deb ad dress, set up" form of this macro is used, the 

I value specified for the setup parameter is used as the index into the 

I SISOCS dataset from which printer setup defaults are obtained. The 

I default region of the SYSOCS dataset must specify FCB, FfiPBB, and print 

I train requirements. 

I then the 'parameter pointer* form of the macro is used, SETUR will fill 

I in any missing defaults based upon the value specified in the SUEFOIH 

I value in the parameter list. In either case, should a required parame- 

I ter not be filled in, SBTOl will issue an appropriate return code. 

Execution: The SETUR macro instruction returns a code in register 15 
I indicating the manner in which the SETBE call was completed. All return 
codes are defined in Figure 35. 



1 

Return 
Code 



Meaning 



I Operation completed successfully. 

4 I Operation not complete; SBTUR macro instruction should be 
reissued. 

8 I Unrecoverable I/O error occurred while attempting to load the 
, device* 
12 J User software error. 
16 I System software error. 
20 I EJE disconnect error. 
24 I Job cancelled. 
28 I Page backup requested. 

lote: for return codes 12 and 16, register 1 will point to a 
prompt parameter list indicating the exact cause of the error. 

I L , 1 

Figure 35. Return codes for the SETOR macro instruction 

then the SITUR macro instruction is executed, the routine determines 
if the present configuration of the printer, specified in the SUE TABLE, 
pointed to by the SDAT, is the configuration requested for this SETOR 
call. If the form, carriage tape (FCB) chain/train, etc., are present, 
control is returned to the invoking routine. If the desired configura- 
tion is not present, the system acts to achieve the desired 
configuration . 

SETOR uses the SISOCS data set to build the necessary blocks to load a 
printer configuration. The SYSOCS data set used may or may not be user 
specified. If defaulted, SBTOl uses the system owned SYSOCS data set 
TSS***'i^.SYSOCS (0) ; this data set contains all the information needed to 
load the 1403, 3211, and 3800 printers. 



204 



S YSOCS : tkis data set is a region data set coasistiag of 4 Msic 
regions. Bach region name is 8 bjtes long, the first two bytes of which 
are predefined by the system. They are as follows: 

1. CltXXXXX — character arrangeaent table region. This region contains 
the inforaation needed to load the OSCB in the 3211 and 1403 printers, 
and the translate tables and WCGHs in the 3800 printer. For the 3800 
printer, it may also contain the naae (s) of graphic Modification 
regions* A aaxiniiii of 12 naaes nay be specified. 

2. FBIIIXII — format control buffer region. This region contains the 
information needed to indicate which density and carriage control tape 
are needed for the 1403 printer, and the FCB specification and density 
settings for the 3211 and 3800 printers. 

3. GFXIxnx — graphic aodification region* This region the pictnre 
iaages needed to built graphic modifications for the 3800 printer. All 
the standard IBH graphic modifications are in TSS*»**^.SYSGSAPH (0) . 

4. standard setup region. This region contains the default information 
needed for a standard printer setup* It is also used to backfill any 
setup information reguired but not specified. 

Example 1 ; the example that follows contains the information needed to 
load the 3211 and 3280 printers with the P11 chain/train configuration, 
this is indicated by the D1¥IC1=321 1/3800, HJkEE=P 11 statements. The load 
information immediately follows this statement (s) . In the case of the 
3211 it is the chain/train image. For the 3800 it is the translate ta- 
ble followed by the iCGM IB. This example does not define the P11 train 
image for the 1403. However, it does indicate where this information 
may be found* The statement I>EVICE=1403,SBE=(P1,1403) indicates the P11 
compatible 1403 chain/train image may be found in the region CTPM of the 
SfSOCS data set. 
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CfPl 

CfPl 
CTP1 
CI^PI 
CTP1 
CTP1 
CtPl 
CTP1 
CTPl 
CTPt 
CTPl 
CTPl 
CTPl 
CTPl 
CTP1 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTPl 
CTP1 
CTPl 
CTPl 
CTPl 



0000100 
0000200 
0000300 
0000350 
OOOOilOO 
OOOOUSO 
0000500 
0000550 
0000600 
0000650 
0000700 
0001000 
0001100 
0001200 
0001300 
0001400 
0001500 
0001600 
0001700 
0001800 
0001900 
0002000 
0002100 
0002200 
0002300 
0002400 
0002500 
0002600 
0002700 
0002800 
0002900 
0003000 
0003100 
0003200 
0003300 
0003400 
0003500 
0003600 
0003700 



Exaaple 2: 



FBSTB6 
fBSTD6 
FBSTD6 
FBSTD6 
iBSTD6 
FBSTD6 
FBSTD6 
FBSTB6 
FBSTD6 



0000100 
0000200 
0000300 
0000400 
0000500 
0000600 
0001300 
0001400 
0001500 



B1?IC1=1403 

D1VIC1=3211 

1»BDJL-5K*C 

1«BDJL-5K't^C 

1»BDJL-5K*C 

1«BDJL--5K*C 

1«BDJL-5K*C 

1«B1>JL-5K*C 

1«BDJL-5K*C 

1«BDJL-5K*C 

EMB 

DEfICE=3800 



,SlE=(Pir^ 

^iriiB=Pii 
(iJia=BO?) 

(HOf=B:#> 
(HAa=lO?) 
(lfO$=S:#) 
(¥AS=BO?) 
CII0$=E:#) 
(»I1=E0?) 
fNO$=B:#) 

t!IIII2=P11 



1403) 

S-.#1>V92«»68<XYT|GF16H. 
SlSRZT9-^G682;irT<XF%H, 
S-.#H>?92"68<XYT fGFXH. 
SIS12f9-^G682;YT<XF1le< 
S-'#1>V92"68<XYT | GF«H . 
SISHZV9-I-G682 ;TT<XF«H . 
S-.#E>f 92"63<Xf T IGFSH , 
SASEZ?9+G682 ;1T<XF%H . 



,_a07/P3iHIQ,4 
._0O7/P3fMIQ,4 
._007/P31MIQ,4 
._007/P3IIEIQ,4 
._U07/P3iMIQp4 
._007/P3»MIQr4 
._007/P3WMIQ,4 
._007/P3fMIQ|.4 



Tl&JSLITE TIBLB 

FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF 
FFFFFFFFFFFF#FFFFFFFFFFFFFFFFFFF 
FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF 
FFFFFFFFfFFFFFFFFFFFFFFFFFFFFFFI 
OOFFFFFFFFFFFFFFFFFFFFOBOCODOSOF 
lOFFFFFFFFFFFFFFFFFFFFlBlClDlBlF 
2021FFFFFFFFFFFFFFFFFF2B2C2D2E2F 
FFFFFFFFFFFFFFFFFFFF313B3C3D3E3F 
FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF 
FFFFFfFFFFFFFFFFFFFFFFFFFFFFFFFF 
FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF 
FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF 
IFO 10203040506070 809FFFFFFFFFFFF 
FF1 11213 1415 16171 3 19FFFFFFFFFFFF 
FFFF2223 242526272 829FFFFFFFFFFFF 
303 13233343 536373 839FFFFFFFFFFFF 

ICGl PUIS 

C82,00) 

GRIPHIC MAilS MAX 12 

EMD 



DE?ICE=1403 

F0HaAT=STANDAKI>^6 

END 

DE?ICE=3211 

F0HMAT=1 (6^1) ,62(6^12) ^66(6^9) 

EHB 

DB?ICE=3800 

F0fiaAT=1 (6,1) ,62(6,12) ,66(6,9) 

END 



The "DE?ICE=» keyword signals tke start of the device dependent informa- 
tion. For the 1403 the operator will be requested to Mount the carriage 
tape ■STASDIfiD* and set the printer density to 6 lines per inch (LPI) . 
For the 3211 and 3800 an FCB image setting the density to 6 with channel 
code 1 at line 1, channel code 12 at line 62, and channel code 9 at line 
66 will be built. 

Fxaaple 3: 

STPAPEE 0000200 PIPEE=1PL1 
STPAPER 0000300 F0HMAT=STI>6 
STPAPER 0000400 CfllRS=F1 1,H1 1 
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I fka default region of tke SfSUCS data set is used hj botli tke SEfUE 

I process aai tke print coaaand. SETHI nsBs ttis region to backfill 

I defaulted values in tke SBTOP request • The print coiaand mses it to 

f fill in defaulted values in the batch work queue. This information is 

I used hj tke batch monitor to schedule print Jobs on the correct printer. 

I At print request time the ■CHIRS=* keyword indicates that either a Pll 

f or Hll train iaage can satisfy the print request. At SBfOfi time the 

I *CH11S=« keyword indicates that the F11 train iaage should be loaded in 

I the printer. PIPEfi type is IPLY regardless of printer type. l*he region 

I FBSTB6 will be used to fulfill the FCB requirements based upon device 

I type. 

I Exaaple 4: 

I In the example that follows two picture iaages have been defined. Both 

I pictures will have a pitch value of 10 as indicated by the •PITCH=» key- 

f word. The keyword ■C0D1 = * defines tiie displaceaent into the translate 

I table where the graphic Modification is to be placed. I aaxiauii of 2% 

I picture images nay be specified in a graphic Modification region. The 

I first line of each picture iaage must specify the code and pitch value. 

I The secx>nd line^ in the above example, is optional and is used for ref- 

I erence purposes onlf . Each picture image laust have 24 lines. The sys- 

I tem will accept a aaximua of 18 characrkers per line. Short lines will 

I be padded to the right with blanks ^ long lines will be truncated. 
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GFGIFI 
GfGBFl 
GFGRF1 
GFGBF1 
GFG1F1 
GFGRF1 
GF31F1 
GFGIFI 
GFGHFl 
GFGIFI 
GFGBFl 
GFGBFI 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGfif 1 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGfill 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 
GFGBFl 



0000100 
0000200 
0000300 
0000400 
0000500 
0000600 
0000700 
0000800 
0000900 
0001000 
0001100 
0001200 
0001300 
0001400 
0001500 
0001600 
0001700 
0001800 
0001900 
0002000 
0002100 
0002200 
0002300 
0002400 
0002500 
0002600 
0002700 
0002800 
0002900 
0003000 
0003100 
0003200 
0003300 
0003400 
0003500 
0003600 
0003700 
0003800 
0003900 
0004000 
0004100 
0004200 
0004300 
0004400 
0004500 
0004600 
0004700 
0004800 
0004900 
0005000 



C0I>1=5B PITCH 10 
123456789012345678 



mm* 






C0I>E=7B PITCH 10 
1234567890 12345678 



mm* mm* 

mmmmm m*mmm 

mmm mmm 

mm* 

mmm 

mmm *** 

mmm *** 

mm* *** 

m^** *** 

mmm *** 

mm********* 

mmm******** 

*** *** 

*** *** 



SETVLQCK — Set VM Lock (O) 

SETfLOCK is used to set a fH Lock. 



I 1 1 

I Mane | Operation | Operand 

I 1 1 — 

([symbol ] I SITVLOCK flock, log [,SET=set] 
I 1 1 



lock 



specifies the VH Lock to be set. 
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log 



set 



Specified as : an EX adiress. 

specifies the fl Lock Inchor to be used to record the status of tke 
spe cif ied lock • 

Specified as : the syabol namiEg a LOGfLOCK macro. 

specifies aa address in the current Module to be branched to if the 
specified lock is already aarked ••set". 

Specified as : an II address. 

Default : fhe status of the lock will not be checked. 

Execution: If the branch address is specified and if the fH Lock Anchor 
indicates "set" the branch will be performed. Otherwise^ the specified 
¥M Lock will be set and the WE Lock Count (ISIfLKCTJ in the task's 
Interrupt Storage Area (CHIISI) WILL BE IICESMBHTED. !fhe address of the 
lock will be saved In the ?1 Lock Anchor for use by OPIfLOCK, etc. 

CAOTIOl: this macro must be protected from task interrupts by I1?I/PTI. 

Programming Mote : lefer to ?i Locking in Section 3. 



SETXP — Set External Page Table Entries fBI 

The SETXP macro instruction allows a range of virtual storage to be 
associated with a set of external storage addresses. It also flags 
pages as "unprocessed by dynamic loader." The first reference to the 
page or pages will then cause control to be given to the dynamic loader. 

J 1 " """ 'I ■ ' ^ ' ^ — I 

IMame | Operation! Operand | 

I 1 1 ^ ^ ^ 1 

I [ symbol ]| SETXP i f 

I I II . . . I 

Mote : There are no operands- 

Initiali zation : A BCLASS macro instrucrtion with the PlIVILEGED option 
must be coded in a CSECT prior to coding SETXP. If more than one BCLASS 
macro instruction is issued in a module, the last BCLASS issued prior to 
coding SETXP must be issued with the PRIFILEGEB option. 

Execution: The first bit of the halfword immediately following the SVC 
is interpreted as a flag. If this bit is 1, the high -order bit of the 
SBA indicates which entry has been processed by the loader. The maximum 
page count is 1022- The low-order 10 bits of the halfword following the 
S¥C are interpreted as a page count- The first fullword following the 
S?C contains the virtual storage address at which the external page ta- 
ble entries are to be set. After this word — and depending on the page 
count — are a number of words; each word contains an external storage 
address that is to be associated with a page in the virtual storage 
range. If the unprocessed-by -loader flag is set for a page, the first 
reference to that page by a program causes cxintrol to be given to the 
dynamic loader via a task-program interruption type 16. 

The external page table entries supplied in the parameter list are 
set as indicated. The unprocessed-by-loader bit is set for each page 
whose bit string flag is a 1 and the high-order bit of the SBA is zero. 
This allows a mixed list to be processed. 
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Retmrn Data : lo&e* 

Bxaaple ; Suppose that yom want to set external page table entries for 
three pages beginning at location MEW. Yon aight write: 



SIIPL 


IX 


a,SET 




B 


S01BPLIC2 


Slf 


DS 
SETXF 


Of 




0C 


H»3» 




DC 


A (MBi) 




DC 


H«12« 




DC 


H«115» 




DC 


H»35» 




DC 


H«51» 




DC 


H«12» 




DC 


a»3«»»' 



SVC MOSf BE OM FOLl WOBD BOOMDARf 

MO BIf STIIIG, THIEE PAGES 

ADD EXTEIMAL PAGE TABLE EMT AT MEW 

SYHBOLIC DEflCE MOHBEE 

RELATIVE PAGE 01 DEUCE 

SYMBOLIC DEVICE lOMBBH 

RELATIVE PAGE OM DEVICE 

SYMBOLIC DEVICE MJMBER 

RELATIVE PAGE OM DEVICE 



SETXTS — Set Pp Extended Task Status Index Field (Rl 

The SETXTS macro instruction enables jon to set the estiaated run 
time of yonr task in the XTSI. 
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I r 



(laae | Oper a ti on | Operand 

I 1 — +- 



|[sfBbol]|SETXTS |[ field] I 

I I ^. I ^ 1 

field 

specifies the XfSI field to be set* 

Specified as s ISTIH^ whick indicates tkat tlie estimated run -time 
field of tlie XfSI is to be set; SBT2i|^ wbick indicates 24-bit ma- 
cbine addressing is to be used; or, if tbe decimal value of 3 (for 
1ST II) or 12 (SBf2i|) is first loaded into register 15, as: (15) . 

Default: It is assumed tbat tbe issued has placed a value in 
register 15. 

Initialization : li BCLASS macro instruction with the P1I¥IL1G1D option 
must be coded in a CSECT prior to coding SBTXfS. If more than one 
BCLASS macro instruirtion is issued in a module, the last BCLISS issued 
prior to coding SETXTS must be issued with the PlIflLEGEB option. 

Execution ; The value in registers and 1 when SETXfS is issued is 
stored in the extended task status index field indicated by the code in 
register 15 . 

Example : Suppose fou want to set the estimated run-time field of the 
extended task status index, fou could write: 



SI 


0,0 


L 


1,=F» run time" 


SETXTS 


ESTIl 



l&HE 

SIPEHOQK — System Performance Evaluation 101 

The SIPESOOK macro instruirtion is assembled into various resident su- 
pervisor modules so that sfstem data maj be collected bf the System 
Internal Performance Evaluation Module (SIPE) 

I 1 — I ^ ^ — ^^- • 1 

I lame | Operation {Operand | 

I , _| ^ ^ ^ 1 

{[symbol fSIPEHOOi: )number-value,hook€:ode— value | 

I I . I ^ , I 

number 

specifies a unigue number for this SIPEfiOOK within this assembly 
module. 

Specified as : a two digit decimal number. 

hookcode 

specifies which SIPE cx^llecrtor is to be activated because of this 
hook. 

Specified as : a three digit decimal number. 

Execution : The action that occurs when a hook is reached is actually 
determined by the setting of an instruction switch located in the pre- 
fixed storage area (PSI) of main storage. (PSA is the term used to 
describe main storage locations 0-4095, which can be addressed without a 
base register.) . When TSS startup is completed, this instruction switch 
contains a BOPl instruction (acrtually, a two-byte BCl isntruction, with 
condition code 0) . 
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flieii control arrives at a hook, this central switch is the subject of 
an IXECUTE instruction. If SIPE is not being usBiL, the WO PR instruction 
is executed, and control flows through the hook, lowever, if SIPl is 
active y the initialization phase of SIPE has reset this central switch 
to an SVC. This SfC is executed bf the hook and results in a transfer 
of control to SIPS, which recognizes the S¥C code as denoting hook 
execution. Basically, the following events occur for a selected hook: 

1. fhe hook is entered, executing the switch in the PSA region 
(SVC) . 

2. The hardware-stored SVC old PSl contains the current machine sta- 
tus and the instruction counter. 

3. The SVC new PSW becomes active. 

(a) SIPE saves all machine registers. 

(b) SIPE locates the hook via the SVC old PSl {instruction count- 
er) and inspects the hook identity code (a constant included 
in the hook) . 

(c) 1 collector is given control to abstract the appropriate data 
for this hook and file it in the output buffer. 

(d) The I/O buffer is output if necessary. 

5. The machine registers are restored. 

6. The SVC old PSl is loaded, returning control to the host module 
at a point just past the hook. 

Example ; Suppose SIPE collector 115 is to be airfcivated in a supervisor 
module. The macro instruction might be written: 

SIPEHOOK 01,1i»5 

This would generate: 

EX 0,PSISIP 
HOP *^* 
OSG *-2 
DC 111(145) 
BC 111(255) 



STORE — Store Register Contents fOI 

The STORE macro instruction stores the contents of one or more 

registers. 



I lame | Operation | Operand 
I 1 1- 



I [ symbol ]| STORE | area, (first register[ ,last register ]) 



area 



specifies the address of the storage area in which the register or 
registers are to be saved. 

Specified as : An RX address, or register notation. If register 
notation is used, the address must first be loaded into the speci- 
fied register. 
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first register 

specifies the first in a range of registers wliose contents are to 
be saved, or the onlf register wliose contents are to be saved • 

Specified as ? I decimal number froa 8 throngb 15, 

last register 

specifies the last register in a range of registers. 

Specified as ; I decimal number not greater than 15. 

Def aolt : Only the register specified in the first register operand 
is saved. 

Programming Motes ; The area mmst be large enough to contain the speci- 
fied range of registers. 



STXfB — SET and ITHCT Table 

The STXTE is a macro used for generating internal tables for use bf 
the three SIT/XTICT rontines — CEAEl, CEIS2, and CliS4. 

I 1 ^^ — I ^ ~ 1 

I name | Operation {Operand | 

I 1 _| ^ ^ ^ 1 

I [ symbol ]| STXTB I table afield , type I 

I 1 . — I ^ ^ ^ 1 

table 

specifies the name of the dsect which is used in each particular 
routine . 

Specified as ; CHITSI for C11H2 
CRISIS for CBIS2 
CHIXTS for CEIS^I 

field 

specifies the field within the dsect which is to be SETup or 
XTlCTed. 

Specified as ; any field within the particular dsect used. 

type 

specifies whether the field can only be XTlCTed or also SETup. 

Specified as : SETUP - setup or extracted 
XTBCT - extracted only 

Programming Notes ; The table generated is in a standard form that the 
SBT/XTBCT modules interpret to perform the correct movement of data from 
virtual memory to the corresponding supervisor tables. 

SYSEB — Indicate Honresident-Program-Detected Error fOl 

The SYSEB macro instruction is the means by which a nonresident pro- 
gram reports errors it has detecrted. 



I 1 ' — I ^ ' 

I Name | Operation | Operand 

I 1 _| ^ ^ 

I [symbol]! SYSEB terror type, fillinrid1,id2,id3, call 
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iai 



M2 



±m 



call 



error tf pe 

specifies the type of error detectel. 

Specified as : One of the codes shown in Figure 23 muter tlie BllOl 
macro iastmction • 

filliii 

aust be inclmled for coapatibility • 

Specified as : Inf two-iigit ieciaal nuBber ia the range 00 tbrongh 

27- 

is the first of three ttEifne identifiers for the message to be is- 
sued when SI SEH is invoked* 

Specified as : I decimal number in the range 1 through S3, 

the second of three nnigne identifiers for the message to be issued 
when SYSll is invoked. 

Specified as : I decimal nnmber in the range 1 through 99- 

the third of three nnigne identifiers for the message to be issued 
when SISEl is invoked. 

Specified as : I decimal mnmber-in the range 1 through 999. 

is used to identify one of several calls in a module* 

Specified as : I decimal number from 1 through 99. 

Initialization : I BCLISS macro instruction with the PlIflLBGlB option 
must be coded in a CSECT prior to coding STSll. If more than one BCLISS 
macro instruction is issued in a module^ the last DCLISS issued prior to 

coding SlSEl must be issued with the PIIVIIBGBB option- 

Execution : The processing unit receiving the S¥SER S?C stops all other 
processing units in the system • .1 message fsee ••SlSBl DOIF" in Section 
5) is issued at the operator's terminal^ the system enters the wait 

state, and, at the installation's discretion, a dump is taken • 

If the error type is 2 (major software) , a program interruption 202 
is fueued on the calling task; this ultimately results in its abnormal 
termination. If the error type is 3 f^^^^^^^ii^^ failure) , the S¥C 228 
routine transfers control to the recovery nucleus. If the error type is 
1 fminor software) , or if the recovery nucleus returns control to the 
SfC 228 routine, all other processing units in the system are restarted; 
control is then returned to the instruction following the SlSEl parame- 
ter list* 

ProciramBincy Mote : Fart of the message issued at the operator's terminal 
is a nine--digit SISEl code; this code is formatted from the idl (aa) , 
id2 (bb) , id3 (ccc) , and call (nn) operands of the SYSEl macro instruc- 
tion and has the form aabbcccnn- This construction permits you to iden- 
tify calls to the system error processor from privileged virtual storage 
modules to facilitate debugging. lou might, for example, assign a par- 
ticular idl code to a group of related modules, assign a particular id2 
code to a subset of this group, and a particular id3 code to a module or 
group of modules within this subset; such an arrangement would identify 
the source of the call to the system error processor, lou could then, 
using the call operand, assign sequential numbers to the SYSER calls is- 
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siiad by tkat Bodiile or group of Molmles to aid recognition of particular 
errors resulting in calls within the sequence. For example ^ fon sight 
write: 



, iti 

I , id2 

I I , ^a3 

I , I , call 

SYSll 1^00,13,6,99,1 

ant the resulting SfSll coie, 130609901, wonli identify the error which 
resulted in the call to the system error processor. 

To avoid the possibility of issuing different SlSEl calls with the 
same SlSBl code (thus duplicating the messages issued at the operator's 
terminal and creating confusion as to the reason for the call) , see Sys- 
tem Messages for those SISES codes already in use in the system. 

Example : Suppose your task detects a minor software error and you want 
to get just the basic SfSEl output, lorn might write: 

BOG SISEl 1,00,2,0,23,01 

TSEHB — Forc^ Time Slice End fRI 

The TSEID macro instruction forces on your task an early time slice 
end. 



I 1 ^-T • • 

IVame (Operation (Operand 



I [symbol] I TSEID t 

I 1 — j_ 



Bote ; There are no operands. 

Initialization : A BCIISS macro instruction with the PlIflLSGBD option 
must be coded in a CSECT prior to ceding TSEIB. If more than one DO. ASS 
macro instruction is issued in a module, the last BCI.ISS issued prior to 
coding TSEID must be issued with the FBITIIEGED option. 

Execution : The current time slice of the task issuing the S¥C is 
terminated. 

Example : If you want to cause your current time slice to come to an 
end, you might write: 

IIZ TSEID 

TSTflQCK " Test fM lock fOI 

The TSTTLOCK macro is used to test the recorded status of a ¥1 lock. 

I 1 1 ^ — ^ ^ •• • 

I lame (Operation (Operand | 

I 1 , ^ ^ . 1 

([ symbol] I TSTVLOCK (log,[ set], [open] ( 

I 1 —I ^ ^ I 

log 

specifies the ¥1 lock to be tested. 
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Specified as s the sjDbol namiiig a LOGfLOCK sacro* 

set y open 

speciff addresses iit the current modiile to be branched to if the 
lock is marked "set* or ••open"^ respectively. 

Specified as : IX addresses. 

Execution : The specified VH Lock Anchor is tested^ and the appropriate 
branch is executed. 

Progratttting ; lefer to VI Locking in Section 3. 

fW&If — Wait for feminal 1/0 Interruption fRI 

fhe flllT macro instrncrtion checks for a response to a message yon 
have sent and^ pending its arrival, puts fonr task in the delay state, 
which causes your task's pages to be moved to auxiliary storage. 

I 1 1 ^ 1 

I name | Operation | Operand I 

I— 1 1 1 

|[symbol]ITllI1? | I 

I I I 1 

lote ; there are no operands. 

Execution : The SfC must be the subject of an Execute instruction and 
must occupy the second halfword of a fullword control block called an 
event control block f^CB) . The resident supervisor checks the second 
bit of the halfvord preceding the supervisor call and interprets this 
bit as the event complete bit. If this bit is 1, the supervisor returns 
control and the SfC is in effect a lOF (no operation) . If the bit is 0, 
and there are any unmasked interruptions gueued on the task, a HOP is 
also affected. Otherwise, the supervisor sets the TfllT flag in the 
task's TSI to 1 and puts the task in the delay state j this causes time 
slice end to occur for the task. The task is removed from the delay 
state when any task -interruption — if the task is enabled — occurs. 

Example : Suppose you send a message to some terminal and are waiting 
for a response. The posting routine associated with the lOCAL (see the 
lOCAL macro instruction) used to transmit the message to the terminal is 
responsible for setting the event-complete bit of an event control block 
to 1. lou have reached a point in your program beyond which you do not 
wish to continue until the lOClL posting routine has been entered. You 
might write: 



TEST 



PFLOW — User Flow for TSS and MTT fRI 

The OFlOl macro instruction is used (for example, by the FLOW 1:0 mm and 
processor) to modify or obtain either the conversational task limit and 
the number of current TSS users, or the multiterminal task (HTT) appli- 
cation user limits and the number of current users £or each application. 



El 
B 


0,TEST-i"2 
lOCOHPLETE 




DS 


OF 


ALIGl 


BC 


H»0» 


POSTIWG FLIGS 
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Ilaae 
I- 



I Operation i Operand 



1 -4- 

|[sfBboll|DFI,01 I 



Bote s There are no operands (see Initialization) • 

Initialization : Before ezecnting this aacro instruction, registers 1 
and Bust be loaded vitb tke following parameters: 

legister 1 

In action code, specifying the action to be taken. 

Code Heaninq 

1 Set the conversational task limit to the value specified in 
the low-order two bytes of register O. 

2 Obtain the number of conversational tasks currently in 
execution and the conversational task limit (see leturn Data 
below) • 

3 Set HTf user limits for each of the application names speci- 
fied in the input buffer that is pointed to by register 0* 
The input buffer must contain: 



7 8 



9 10 11 12 13 1il 15 



J . ^ ^ ^ 

Ipplication name (1) 



IHTT 

I user 
I limit 

1(1) 

i 



Application name (2) 



I ITT 
fnser 
I limit 
1(2) 



etc« 



The application name must be left-aligned and consist of up 
to eight alphameric characters; the first of which must be 
alphabetic. Setting the application name to X*FP« indicates 
the end of the buffer list, for both acrtion codes 3 and 4. 
The MTT user limit mmst be specified in binary. The low- 
order bytes that are not nsed must contain blanks. 

4 Obtain the number of ITT users in execution for each appli- 
cation name that is currently active in the system, legist- 
er must contain the address of a virtual storage buffer 
into which the application names and the statistics pertain- 
ing to each can be recorded when the requested processing is 
performed • 

legister 

Either the conversational task limit, representing the total number 
of TSS users that may be logged on concurrently, if airtion code 1 
is specified, or a virtual storage buffer address, if action code 3 
or 4 is specified. 

The task limit that is specified in the two low-order bytes does 
not affect usc^rs that are already logged on. If set to zero, no 
additional users may logon to TSS; the maximum must always be less 
than or egual to the syst^i maximum. Any virtual storage address 
that is specified should point to a buffer that starts on a page 



Section 2: System iacro Instruction Descriptions 215 



boQUdarj and does not exceed a page length.* This address can point 
to either an input buffer (see action code 3) or to an output buff- 
er (see action code 4) • Two sfstea BSlCTs, CHIO?L and CHIOFI, 
respectively, are available within TSS for use in referring to 
fields in those buffers. 

I DCL&SS macro instruction with the FlIflLEGED option wust be coded 
in a CSECT prior to coding OFLOff. If more than one BCLASS macro in- 
struction is issued in a module, the last DCLISS issued, prior to coding 
QfLOl, must be issued with tbe PlIflLlGBD option. To ensure (for action 
codes 3 and *») that the buffer will be in main storage when UFLOl is 
executed, an HfC instruction must immediatelj precede the UFLOl macro 
instruction • 

CAPTIOMS ; Use of 1IFI,01 (which produces an SVC 187) is restricted to 
tasks having sj stem programmer authority (O or P) . Iny virtual storage 
buffer that is provided must not go over a page boundary. 

Execution : The privilege specified by the DCL&SS macro instruction is 
verified. If acceptable, the action code is validated. For action 
codes 1 and 2, the appropriate limit field, conversational TSS task 
limit (action code 1) , or the ITT application user limit (action code 3) 
is set in the multiterminal status control block (HTSCB) . For action 
codes 3 and **, the requested statistics (current number of conversation- 
al TSS tasks or current number of ITT users on a specified ITT applica- 
tion) and the system maximums for such limits (see Programming lotes) 
are recorded in the buffer. All error conditions are identified by re- 
turn codes or, for action code 3, in the original input buffer (see Re- 
turn Data below) . 

Return Data : 

Register 

For successful execrution of action <:odes 2 and 4, contains the re- 
quested TSS or ITT statistics in the form: 



For action code 2: 




15 16 



31 



{Current number of 
I conversational tasks 



{Conversational task limit 
f 



For action code ft: 



7 8 



9 10 



11 12 



I 1 1 1 

IppHcation name (1)| Current HTTfUser limit| Maximum number 

I users I I of users 



13 1ft 

— I 



15 



+ 



+ 



+ 



Application name (2) [Current HTTIPser limitflaximum number 

{users I I of users 



etc. 



The application name must be left-aligned and must consist of up to 
eight alphameric characters, the first of which must be alphabetic. 
Ihen the application name field contains hexadecimal Fs, it indi- 
cates the end of the output buffer list. The low -order bytes that 
are not used contain blanks. The current HTT user value, the HTT 
user limit, and the maximum number of HTT users are all binary 
values. 
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For action coie 3: register poiats to tlie input buffer aM maj 
coataia error iadicatioas: 

1. If aa applicatioa aa«e is noaexisteat^ the two kalfworis start- 
iag at bjte 10 ia tlie iaput buffer are set to X»FFFF». 

2* If the BaxiBUB allowable user limit (recorded ia IfSEIl ia tke 
HTSCB) is exceetedr tbe two bal&ords startiag at bjte 10 ia 
tke iapat buffer are set to €»*♦•', aai the ®axi«ii« value is 
placed ia the aext half word fat bjte 11). 

legister 15 

Coataias a retura code: 

Code Meaaiacf 

normal coBpletioa 

4 Coaversatioaal task limit is larger thaa maximum value 
(ETSRIl) for actioa code 1 

8 Ictioa erode specificatioa error 

12 Buffer exceeded page bouadarj 

Proqrammiaci Motes s The iaitial TSS c»a versa tioaal task limit is estab-- 
lished duriag system geaeratioa with the TSKLIT macro iastructioa (see 
System Geaeratioa aad Haiateaaacel ; the aumber of HTT admiaistrators (or 
ITT tasks) is iacluded ia the cx>uat of coaversatioaal tasks. 

The u^r limit specified for each ITT applicatioa program with OFLOW 
caa aever exceed the maximum value origiaally established by the ITT 

admiaistrator whea he issued aa HTT commaad* 

Before OFIOW is first issued., a GITIIII macro iastructioa caa be is- 
sued to get the buffer,, which €m.n be retaiaed for the duratioa of the 
task. 

If a coaversatioaal TSS task eads abaormally (completioa code 2) , a 
aew task is created regardless of the «>aversatioaal limit. 

I commaad, FLOW, available oaly to system maaagers, admiaistrators 
(see Maaaaers aad Admiaistrator *s Guidel , aad operators (see Operator's 
Guidel , caa be used dyaamically to modify the aumber of coaversatioaal 
or batch tasks. 



PPDTOSEB — gpdate Pser Tables CO) 

The IPDTPSll macro iastructioa causes the data pertaiaiag to exteraal 
storage that is curreatly ia each user table ia the SfSOSE data set to 
be updated with iaformatioa from the various user catalogs aad DSCBs. 

I 1 --I • • ^ ^ -~ — — — -~ — — — ^ ^ ^ — ^ , 

IVame | Operation (Opera ad | 

I 1 ^ _ . ^ ______ ^ 1 

|[symbol]|OFDTIISBl |[mode] | 

I 1 ^-1 _ — ^ — ^ — __ — ^ — -^ ^ ^ I 

mode 

specifies whether all or select user eatries ia the SlSPSl data set 
are to be updated. Select users are those users with curreatly ac- 
tive tasks aad those users owaiag shared data sets that are cur- 
reatly beiag accessed. 

Sectioa 2: System lacro Iastructioa Bescriptioas 217 



Specified as : I - all 

S - select 

Default ; I 

Initialization i 1 DCLISS Macro instruction vith tlie PEIflLESBD option 
Bust be coded in a CSECT prior to issuing OPDTIISEB. If more than one 
DCLASS aacro instruction is issued in a nodule, the last BCLISS issued 
prior to eroding OFDTOSll aust be issued with the PRI¥1LS6ED option. 

Execution: tJPDTUSEB updates the cuBulati^e page count fields in the 
user table data set (SISOSE) by extracting the infornation from each 
user^s catalog and each referenced data set's for»at-B DSCB. Teaporarf 
public data sets are erased, the total nuaber of pages assigned to each 
user table is changed to reflect the values indicated by their DSCBs^ 
and the temporary and external storage allocation fields are updated. 

If Bode S is specified, only those entries whose users were active at 
the tiie of issuing UPDTUSEB (or, if the systea failed and was 
restarted, users who were active at the time of systen failure) are up- 
dated. ("Ictive" here aeans active task or with a shared data set that 
was being read, fhe flag OSSikDC in the user entry indicates an airtive 
user.) 

Return Data : 1 message signifying the ix^apletion of the update is writ- 
ten to SISOQT, a return code is placed in register 15, and control is 
returned to the issuing program. 

Return Codes Meaning 

00 Sormal return 

Qf^ DSCB error or improper authority code 

Example : A privileged system programmer has previously issued an RFS or 
C¥? command, or has decided that many user tables have become obsolete. 

User: UPDTUSBR 

System : Returns the following message to SISO0T: *nnnn USER TABLE 
STORAGE ALLOCATIOIS UPDATED AGAIHST DSCBS.«» 

Programming Motes : Following an RFS or C?¥ command, an UPDTUSER command 
or macro instruction should always be issued. UPDTUSER may be issued 
without a preceding RPS or CW. 

UPDTUSER facilitates the conversion from an old user table entry 
DSECT to a new one. 

If the user table is suspected or known to be in error, issuing UPD- 
TUSER causes the current catalog and DSCB information to be placed in 
the user table. 

If the user table is up to date except for active users, which may be 
true following a system failure and restart, the use of mode S speeds 
the updating. 

Any temporary public data sets are deleted by issuing UPDTUSER - 

When the user table of the task issuing UPDTUSER is itself updated, 
the shared virtual storage of that user table is updated to correspond 
to the updated STSUSE record. 
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PSAgB " DisplaT Resoggce Psaqe fSI 

TMs mmcro instmctioii obtains aecountiEg data that has been acci»ii- 
lated for a user. 

USIGS is described in Asseabler User Macro Imstructions ^ except for 
the folloving inforaation that is applicable onlj to sjstea programmers 
(anthoritf codes O or F) . 

aserid 

specifies the address of a location csontaining the Qserid of the 
user for whom the accounting data is regnested^ (i nonprivileged 
user may obtain onlf his own acconnting data; a system programmer 
may obtain the acconnting data of any nser.) !Phe nserid at the 
specified location most contain one to eight alphameric characters, 
the first character mnst be alphabetic, and the nserid must be 
delimited by 1»27». 

Specified as ; 1 relocatable expression, or, if the address is 
first loaded into the specdfied register, in register notation. 

Default : The issuer's userid will be used. 

OSIEOCK — Lock Pser Table Entry fOI 

The OSELOCK macro instruction is used to lock the virtual memory copy 
of a user table entry. 

I 1 -T ' 1 

I lame (Operation {Operand | 

I 1 -I ^ ^ 1 

I [ symbol ]|irsiLOCE | | 

I I —I ^ ^ I 

Mote ; There are no operands. 

Initialization ; The program issuing the USELOCK macro must have previ- 
ously set up base registers for task common (CHITCH) and the user table 
entry (CHJlllSE) . 

Execution ; The OSILKCIT is loaded into general register 15 to control 
the number of time slicse ends that will be issued. The lock byte is 
then tested with a TS instruction. If successful the task id is moved 
from task common to the user table entry and processing continues. If 
the TS instruction was unsuccessful, a time slice end is issued, the 
count in general register 15 is decremented, and the lock byte is tested 
again, then the count goes to zero, processing €;ontinues as if the TS 
instruction had been successful. 

VBHEB — VAH Data Management Error Recovery fS) 

The VDHER macro instruction provides an error exit for attempting 
recxivery or issuing diagnostic messages when error conditions arise 
while pro€:essing VIH data sets. If used conversationally, VDREl issues 
diagnostic messages and returns to the user's terminal without termi- 
nating his task. If executed nonconversationally, diagnostic messages 
are written to the S7S0IIT device, and the task is terminated. 

Standard form; 



I 1 ^-1 

flame (Operation {Operand 
I 1 ^+ 



|[symbol]|VDHEl |dcb address, message id, flags 
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Is- and l-forns: 

I J 1 J 

I lane (Operation (Operand | 

I 1 1 ^ 1 

|[sjBbol]t?l>lllB |dcb address, message id,flagSrEF=p,( (l,list)} | 
I 1 1 1 

lote: K symbol is required in the name field of the L-for». An operand 
omitted from the L-form must be specified in the B-form; an operand 
specified in the L-form is overlaid by the same operand in the 1-form* 

deb address 

specifies the address of the data control block (BCB) for the data 
set in error • 

Specified as ; I relocatable expression or register notation (2 
through 12) . If register notation is used, the address mast first 
be loaded into the specified register. 

message id 

specifies the address of the second word of a parameter list that 
contad.ns the identificration number of the diagnostic message for 
the error condition. If there is variable data to be supplied for 
the message, pointers to the variable inserts follow the message 
IB, and a one-byte count of these pointers will precede the message 
ID (see below) • 

I — I 1 1 1 1 1 

I C [ kkhh I kkkh [ P »P t P tp» ( pzpzpzpz I po , . . I 

I I 1 1 1 I I 

C = One-byte count of pointers (may be zero) . 

I = light -character message ID. This doubleword is 

addressed by word 2 of the parameter list. 
P»,P2^...pii = Four-byte pointers to variable data, 
if any. 

Specified as s k relocatable expression or register notation (2 
through 12) . If register notation is used, the address must first 
be loaded into the specified register. 

flags 

specifies the address of a two— byte field where: byte 1 indicates 
the type of error that occurred, and byte 2 indicates additional 
information about the error. The flags and their meanings are: 

Byte 1 Meaning 

•10« EODID or SYIID condition 

•20» Clear last operation flag 

Byte 2 Meaning 

■0A« Called by one of the OPll modules CZCOI, CZCPl, CZCOP 

»0C» SDST error in CZCOI 

■01 ■ Hon-¥lM data set in CZCOZ 

Specified as : k relocatable expression or register notation (2 
through 12) . If register notation is used, the address must first 
be loaded into the specified register. 

Execution : fDMll closes the data set that is causing the error. If it 
was open, a temporary close (CLOSE, type T} is issued on all the data 
sets associated with that task. Diagnostic messages are written to the 
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NA Md one or more new aliases, 

NAR Add one or more new aliases and retiarn duplicate aliases, 

R Replace the user data associated with a member and close 

the member, 

U Replace the user data associated with a member but do not 

close the member. 

D Delete a member from the data setj the directory entries 

for the member and all of its aliases are deleted and the 
space occupied by the member is irade available for subse* 
qnent. use, 

DA Delete one or more aliases, 

C Change the name of a member. 

CA Change the name of an alias. 

Initialization s If this macro instruction is tc be executed in a privi- 
leged module^ the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M), Also^ the 
address of a save area must be placed in register 13 before this macro 
instruction is executed., 

CAPTION S A mamber may not be subsequently referred to 1^ the same data 
control block after a type-N or -R STOW until a FIND of that mexiiber is 
again requested^ since these types of STOW close the member, 

STOW abnormally terminates the task if any conditicns are discovered 
that make continuation impossible, 

Proqramminq Notes : Ctoly type-R STCW is permitted on a shared data set 
opened for input. The format of the user area used by the STOW macro 
instruction depends on the type of STOW requested. It is the user's re- 
spoi^ibility to construct the area and pass the address of the area to 
STOW in the user area operand of this macro instruction. The area re- 
quirements are: 

Types N and O ; The area must be at least 12 bytes long and begin on 
a fullword boundary. 

bytes I 8 | i| | n | 
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Name | N | Dser Data 



Name - Eight -character m^nber name 

N - Number of bytes of user data C0SNS510) 

User Data - Contains the variable data supplied by the user. The 
data is stored in the POD and can be retrieved by 
means of the FIKD macro instruction. 

Types NA> NARy and DA ; The area must be at least 20 bytes long and 
begin on a fullword boundary. 
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J. . ^ — ^ ,. ^ ^ J. ., ^ 

bytes I 8 |4I818| IBf 

I Member Name | M | i^lias 1 | Alias 2 | •.-. ] Alias M | 

L . J Jl X , X ^ J J 

Member Name - Name of the member to which the aliases are linked 
or are to be linked, 

M - Number of aliases to be added or deleted- 

Aliases - The aliases to be added or deleted. 

Note: Type-NAR STOW causes duplicate aliases to be stored in a page 
provided by a GETMAIN macro instruction. The first word of this page 
contains the count of duplicate aliases. The STOK macro instruction 
places the address of this page in register before exiting. 

Type D : The specified area must contain the member name that is to 
be deleted. It is eight bytes long. When a member name is deleted ^ 
all of its aliases are also deleted. 

J.- , . ^ . . ^ 

bytes I 8 | 

|. ^_„ n 

I Itember Name | 

Type C ; The name of the member and the name to which it is to be 
changed are in this area (16 bytes). 



^ ^ ^ . . ^ ,.-. 



bytes I 8 I 8 | 

I Member Name | New Member Name | 

Type CA s The area specified must be 24 bytes loi^. 

bytes I 8 f 8 I 8 I 

I 4„ ^^+ 4 

I Member | Old Alias | New Alias | 



Member - The eight-character name of the member with which the 
old alias is associated. 

Old Alias - The eight- character alias being changed. 

New Alias - The eight- character alias being used for the 
r e p 1 ac emen t. 

Type R ; If any user data is specif ied^ the length must be four bytes 
longer than the length of the data and the area must begin on a full- 
word botmdary. The additional four bytes are required to specify the 
length of the specified data. 



-1 



bytes I 4 I N I 

I N I User Data | 
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II - Sumber of bytes of user's data to be placed in the POD (a 
number from 1 to 510) . 

User Data - Contains the variable data supplied by the user. The 
data is stored in the POD,, and can be retrieved by 
means of the FIND macro instruction. 

The user must have erclusive access to a member in order to issue 
type-C or type~D STOW; that is, he must have opened the data set with an 
OPEN option that causes the member to be write-interlocked . 

Member interlocks are released by CLOSE (referring to the same DCB 
that caused the interlock to be set) , tyoe-R STOi,, or a subseeuent FIND. 

Eules for sharing ?PAH data sets are also given in Appendix K. 

Return D ata : ?ifter execution of the STOW macro instruction, bits 2U 
through 31 of reqister 15 contain one of the followinq hexadecimal codes 
indicating the statas of the ©Deration. The user should examine this 
code to deteritine the course of action. 

Coie Meaning 
00 Successful completion of STO« 

0^ Mew name or alias is already in use (1, NA, NAP , C, or 

CA) 

3 HeEiber name is not in POD (U^ D, DA, or CA) 

10 Old member name is not in POD (C) ; alias is not in POD 
(DA) ; oil alias is not in POD (CM) 

1^ Invalid type STOk requested (STOW out of range, aember 
nape FFFFFFFF specified, input area not on a fullword 
boundary, or STOii NA ani alias count 0) 

1& User data ezzcee<ls maxiausi length of 510 bytes. 



S YSI:^ -- Obtain Input Line Froa S Y SIM or the Source lis t (S) 

Ine SY3IJ macro inrtruction either prompts the user's SYSI!j device 

£or an inout line, or it reads a line froa the Source List. The input 
line Day consist of a ^.essage, a command, or iata- 

Standard rorm : 

I -i , ^ ^ , 

niaae fOoeration | O^eranS I 

|. ^ 1_ ^ , 

f [ symbol ] fSYSi'i | inout line area, length of input line area, | 

I I IfsO'Urce coie ],[ pronpt character ][, exit address] | 
I I I I 
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L- and S-form: 

I 1 1 1 

I Name f Operation | Ooerand I 

I J 1 f 

I [ symbol ]| SYSIM |[irii»ut line area ],[ lenath of input line area], I 
I I |[£Ource cole },[ prompt characters 1[ , exit aicresFlr I 
J I ffF=CII (F,list)} " ' I 
I I 1 1 

^ote : k symbol is raguirel in the name field of the L-foEE- The oara- 
meters specified in the E-forro will overlay those specified in the L- 
form of the macro instruction. The F-form say not specify more operands 
than are specified in the L-form. 

input line area 

specifies the address of a user s-corage area in which the SYSIN 
macro instruction is to store the reo nested input line. 'Jo boun- 
dary requirements exist for this operani. 

Specified as : In the standard and L-form, as a relocatable expres- 
sion; in the standard and F-form, in register notation (? through 
12); in the E-form only, as an EX address. 

length of input line 

specifies the address of a fullwori that specifies the nuF-her of 
bytes in the user's inout line area. if the reauested inout Mes- 
sage is too long for the specified storage area, it is truncated on 
the riaht. The four low-order bits of register 15 contain a return 
code of X«04' if truncation occurs- If the requested inpat line 
lengtii is less than the number of bytes in the user's area, the 
contents of this fullworJ are replaced by the actual number of 
bytes transmitted. 

Specified as: Same as the first operand. 

source code 

specifies the source from which the input line is to be obtained 
and the location to which it should be transmitted . 

Specified a s: A one- or t¥o-byte code. The first byte serves as 
the source code ani the second byte, if present, indicates that 
commands are to be transmitted to the user's input line area. If 
only the source code is specified (that is, the second byte is left 
blank) , the transmittal location is as indicated under the various 
source codes. The source and location codes are: 

S ourc e Code Meaning 

L Obtain the input line from the Source List (created 
by the system Co'imand ]^nalyzer routine) ard return 
normally if the line contains a message or data. 
If the inout line is a command, a return is made to 
the specified ezit address without obtaining the 
coainiand. If the input line is a command but no 
exit address is specified, a return is made to the 
caller with a return code of X«OC». If there is no 
data to be processed, the return code is X't^O'. 

G Obtain the input line from SYSIH and, if it con- 
tains an input line or data, return normally. If 
the message is a command, transfer the com and to 
the Source List, but do not transmit it to the 
user-specified storage area. If the input line is 
a command but no exit address is specified, trans- 
fer the command to the Source List and terminate 
the program normally. 
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Obtain the inptit line from either SYSIN or the 
Source List^ depending on the setting of the SYSINX 
parameter established in the user*s profile by pre- 
vious issuance of a D1FAUL1 coirmand. The value of 
the SYSINX parameter in the user profile might have 
been previously established as either G, Z, or !• 
If the source operand is defaulted when issuing the 
SYSIN macro instruction, the source code existing 
in the user profile establishes the actual default 
code, SYSINX is initially set to G by the system. 



Location Code 



This code may be used as a suffix to any of the 
first three codes, but may not be used by itself. 
It modifies the action of the code to which it is 
suffixed by causing command to be transmitted to 
the user's input line area just as ordinary data or 
message input would be. 



Default: 



proippt characters 

specifies a special command prompt character or string that is to 
be issued at the user's terminal to prompt the user to enter an 
input line. The indicated prompt string should be preceded by one 
byte containing the string length. 

Specified as : Same as the first operand, 

exit address 

specifies the addr^s that is to receive control if the requested 
message is a command and the source operand is not specified with 
the S as a suffix. This operand is not valid if the source operand 
is specified as hS, GS, or IS, This operand must be specified if 
the source code operand is not specified with the S suffix. 

Specified as ; Same as the first operand. 

Initialization s If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLMS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M>, Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

Programming Notes ; When the input line is read, it is examined to de- 
termine if it contains commands, an input message, or data. If an input 
message or data was read from SYSIN or the Source List, the input line 
is transferred to the user-specified input line area and execution of 
the user's program continues. However, a user may have entered a com- 
mand or command statement in response to the prompting produced by 
execution of the SYSIN macro instruction. If the reply from SYSIN or 
the source List is a command or command statement, it is not transmitted 
to the user-specified input area unless the suffix S appears in the 
code. Instead, the SYSIN routine passes control to the user- indicated 
exit address. At his exit address, the user can then examine the com- 
mands by searching the Source List, and either execute them immediately 
and continue processing, or execute them further on in his program. 

A user can alter the action of the SYSIN routine by Altering the sys- 
tem prompt character (an underscore) following the SYSIN macro instruc- 
tion routine's prompt string when it is written out at the terminal. If 
commands are entered in this manner, they are executed immediately and 
the SYSIN routine returns a code of X'OC in register 15 to the user. 
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If the suffix S is used, coimarands are transmitted to the user' s input 
line area, just as data normally is. 

If a line is requested from the Source List when the latter is empty, 
the message is obtained from SYSIN instead- 

Return Data ; The hexadecimal return codes placed in register 15 when 
control is returned to the user are shown in Figure 16, 

^en a normal return is made, the total number of bytes transmitted 
to the user area is passed to the user in the area in which he indicated 
the maximum message length. If source code L is specified and a null 
line (that is, a zero-length record) is detected as data, SYSIN com- 
pletes successfully and returns an indication of the zero length in the 
maximum message length area. 



[Bits 16-23 Code | Significance 




— ~H 



Input record contains no continuation code? record 
is therefore complete. 

Input record contains a continuation code; issue 
another SYSIN to obtain next porticn of record. 



8 
C 



10 



20 



40 



Task is nonconversationalj normal return made. 
Record truncated (exceeded maximum input length 
specified by the user) . 
i^ttention interruption occurred. 

An immediate command (a command preceded by the con- 
trol language prefix character, normally an unde- 
rscore) was detected and executed. To restime execu- 
tion, a nonpriviliged program must issue a GO com- 
nandi if a privileged program issued SYSIN, the pro- 
gram cannot be resumed and it icust be reinvoked. 
Task is conversational? SYSIN received from terminal 
keyboard or source list? normal return made. 
Task is conversational? SYSIN received from terminal 
card reader? norital return made. 
SYSIN request not processed. 

Figure 16. Return Codes from SYSIN macro instruction 



Note: Various combinations of the above return codes may also be re- 
ceived. For example, a return code of X"14* indicates that the task is 
conversational, input is from the keyboard, and the reccrd is truncated- 

An example of L- and E-form use is: 



SUE 



SYSIN 
SYSIN 



INAREA ,LENGTH ,G ,PMPT ,EXITEND ,MF=L 
LENGTHS , ,PMPTB , ,MF= ( E , StJE) 



When the E-form of this macro instruction is executed, the length of 
the input line area and the prompt character operands (LENGTH, PWPT) 
specified in the L-form are replaced in the parameter list by the length 
and prompt character (LENGTHB,PKPTE) specified in the E-form. 
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ExaiBple : Execution of the following example causes the prompt charac- 
ters •EIITEB ID* to be displayed at the user's terminal, and his reoly to 
be rea^i froiR the terminal and transmitted to the input line area labeled 
I'JAREA- The number of bytes transferred to I^ARTA is placed in the 
LENG'iH xield soecified by the user. When the SYSI^ routine returns con- 
trol to the user's program, register 15 coT^taiBs a return co3e of X • 10 • . 

The example is: 



ttVC LENGTH, LCOH 

S¥SIN IllJtFEa ,LEIG1B,G,PB.0M?T,SXITADP 



21 Id ADR RErURM 





EC 


All (L'PROKPT) 


PROMPT 


DC 


C 'EMTER II' • 


LCOll 


DC 


A (L •IN? PER) 


LENGTH 


DC 


F»0» 


IMASEA 


DS 


CL20 



LENGTH OE PROMPT STRING 
LENGTH OF ISAHEA 



T R l> p p _ 2 - ^ T r u n c a t e a b_ Output Suffer (R) 

The idOKC leacro instruction (for QSAfI) causes the current output 
buffer to te reqarded as filled. The next POT macro instruction will 
use the nezt block to hold a logical record. 



I Mame 
I 



IGoerat ion lOoerand 

H h— 



^[symbol ]|TRUMC 
I I 



f deb address 



deb address 

specifies the address of the data control block opened for the out- 
put data set. 

J Specified as ; Register notation (1 through 12), or an RX address. 

CAOTIQJ : A TRu^C iiacro instruction will be ianored if used with 
unblocked records, or when a buffer is full, or if it immediately fol- 
lows another TRONC macro instruction. 

The TRU^C macro instruction is Bteaningful only with tormat-F and -V 
blocked records. Its use with foraat-P blocked records means that the 
data set cannot be considered to contain standard blocks. When the data 

set is read, the RECEfl operand of the DCB macro instruction must not 
contain an S. 

P rogram mina Notes; Any exceptional condition resultina from the execu- 
tion of a TRUNC macro instruction causes control to be passed to the 
user's tynchronous error exit (SYNAD) routine - 

I If a TPU^C is issued on a data set opened for OPDAT (see the OPIH 
I macro) , the following G?rT retrieves the first logical record from the 
next block. The last block is written out, including all logical rec- 
ords read plus those not updated by a PUTX. 

If a IRUNC is issued before the first PUT of a data set, the TBOKC 
macro instruction is ignored. 
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fTIMER — test Interval liiaer 10) 

The TTIHEB macro instruction indicates the time remaining in the 
interval requested by a previous STIMEP Dacro instruction and, optional- 
ly, cancels a previously specified timer interval. 

I 1 1 1 

I Name (Operation | Operand f 

I 1 1 ^ 1 

|[ symbol]|TTIMER | (TASK | REAL) [, CANCEL ][ ,THO= {timer number}] | 

I 1 1 1 

TASK 

specifies a TASK interval, as specified in the associated STIMEE 
macro instruction and as identified in the exit list specified in 
the STIWER macro instruction. 

Specified as: 1!ASK 

REAL 

specifies a REAL intervalr as specified in the associated STI.^f^R 
macro instruction and as identified in the exit list specified in 
the STIMEB macro instruction. 

Spec ifie d as : HEAL 

CANCEL 

specifies that the identified interval is to be canceled. If the 
interval expired before the TTIMER macro instruction was executed, 
the CANCEL operand has no effect - 

Specified as : CANCEL 

Def aul t: If this operand is omitted , processing continues with the 
unexpired portion of the interval still in effect. 

TNO = 

specifies the number of the prograame-^ interval timer -co be rested. 
Honprivileged programs may test timers to 15. Clocks 8-15 may be 
tested but they cannot be canceled; clock numbers over 15 are con- 
sidered invalid. 

Specified as : A number. 

Def ault : If this operand is omitted or invalid, timer will be 
assumed for nonorivileged orograms. 

Return Data: 'lihen control is returned to the user proqram, one of the 
following return codes is Dlaced in register 15. 

Code Me ani ng 
00 Successful completion. 
04 Invalid clock number was specified - 

The time remaining in this interval is returned ii^ register 0, ¥het!i- 
er or not the interval is canceled. 

The remainina time appears as a 32-bit unsigned binary number in 
which the least significant bit has a value of 1 millisecond. "^he 
interval is returned in this form even if the interval was originally 
specified in decimal digits. If the interval expired and the event has 
already been dispatched before the TTIK^Tt macro instruction was issued, 
a zero is returned in raaister 0. 
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Initialization : This macro instruction cannot be assembled in a privi- 
leged module unless the most recently issued DCLASS macro instruction in 
the assembly specified USEE (see Appendix M) or if the DCLASS option is 
OSES by default. 



USAGE -~ Display Eesoi^rce O sage ( S) 

The OS AGS macro instruction causes the user^s resource statistics, 
nhich are accumulated during his use of the system, to be displayed in 
an area defined in his program. 

Standard form: 

I 1 1 ^ 1 

I iame [Operation | Operand | 

I- 1 1 ^ 1 

I fOSAGE laser area adaress[ , user identification] f 

I 1 1 ^ . 1 



L- and E-f orm : 

f 1 1 ^ 1 

fMame |Operation lOperand I 

I- f— f ^ f 

|[ symbol IJUSAGE |[u3er area address ]r , user identification] f 
I I I ,H?={L| (E, list) I " I 

I i I I 

Note : A symbol is reauired in the name field of the L-form- Any 
operand that is not specifi€=d in the L-fora oust be specified in the 
corresponding E-torm of the macro instruction - 

user area adiress 

specifies the address of the area in a user Drogram where accuinu- 
lated accounting statistics can be recorded for subseouent user 

reference. The user area should be ^00 bytes. 

Spacit i ed as : In the standard and L-form, as a relocatable expres- 
sion; in the standard and E-form, as in register notation {? 

through 12) ; in the F-fom only, as an RX address - 

user identif icatioR 

specifies the address of the user's identification code. When 
soecified, the user IL must be coded elsewhere as one to eight 
alphameric characters, with y*27» following the last character. 
The first character must be alphabetic. A nonprivileged user must 
always specify his own user ID. Privileged users may specify any 
user ID (see Sys tem Proqraroffier's Gui de, GC28-2008 for further 
information) . 

Spe cii iel as: See the first operand. 

D e L a ill t : The current user identif ication- 
iiy^ialization : If this macro instruction is to be executed in a privi- 
lege! module, the aost recently issued DCLASS macro instructior in the 
assembly must have soecified PRIVILEGED (see Appendix M) . Also, the 
address of a save area niust be olaced ir. register 13 before this macro 
instruction is executed. 

CP.UTIOK : It a user current, task attempts to use more system resources 
than have been allowed hiii in his User Limit Table, the user task is 

abnoritally terminated. 
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Proqram ffi ina N otes: ThQ syrtsx iaaintains a master resource scheduling 
table (SYSULT) which, controls the amounts of system resources any one 
user is allowed to employ. Each user has a unique User Liait I'able piade 
available to him when he is joined to the system. Ihe user's resource 
usage statistics are maintained in this table by the system. 



USAG!^ records statist 
permanent or private sto 
CPU time, connect time, 
the user. These statist 
system resources the use 
well as the accumulated 
system resources since h 
could be useful to progr 
sections of their progra 
gaired by management. 



ic£ for device allocation, number of paaes of 
rage allocated, total number of active tasks, 
and bul^ input/output operations performed by 
icE reflect both tne current amounts of various 
r aas assigned to hia at any point in a tasJc as 
statistics relating his total usage of various 
e was joined to the system. These statistics 
amners in determining the efficiency of various 
ms and for recording budgetina statistics re- 



Inforaation recorded in the user specified area can be examined by 
his program and, if desired, printed out on the SYSOOT device, in the 
following format: 

TEMP STOB=ration;current;accuii/PERM STOR=ration :current ;accum/DA DEV = 
ration; current/K AG 1 AP=ration;current ; accum/P3IMTERS=ration/ 
current ;accum/PD PUN=ration; current; accun/lSS TASKS=ration; current/ 
B0LKIN=accuiL/BULKOUT=accum/CU TPIHE=ration : currant ;accuit/CO!IS 
TIKE=ration;current ; ace am 

where the printed values represent: 



PEHH STOR 
TEMP STOR 



DA DEV 
MAG lA? 
PBINTERS 
RD-PUM 



I /^ration = 

"^ current = 

^accum = 

fration = 
' current = 



ULKIH 1 
ULKOUT J 



COMll TIPE 



CPU TIME 



k current 

accum 

ration 

current 

accum 



number of pages available for user's data 

sets 

number of pages currently occupied by user's 

data sets 

accumulated number of pages times number of 

seconds they have been held to date 

number of devices of this type available to 
the user 

number of devices currently assigned to user 
number of such devices multiplied by the 
number of seconds for which they were assign- 
ed to the user 

accumulated number of bulk input/outPut 
operations since the user was joined to the 
system 

maximum amount of time that the specified 

user can be connected to the system from a 

terminal (hhh:ffiE:ss) 

number of hours, minutes, and seconds since 

the user logged on (hhh:mn:ss) 

total of all connect time during accounting 

Period (hhh:ffim:ss) 

naxiraum amount of CPU execution time perFitt- 
ed to tasks associated with this user identi- 
fication (hhh:i!m:ss) 

number of minutes, seconds, and milliseconds 
of CPU time used since the user logged on 

(mm:ss:ms) 

number of hours, minutes, and seconds of CPU 
time since the user was joined to the system 

(hhh:mm:ss) 
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Ex atitpl es : The user wants to iisplay his resource usage statistics at 
soae point in Iiis program. He records those statistics in 400 contiq- 
uous bytes starting at STAT&RSJl and then prints ther out on the SISOU'T 
device with two successive GAT'^B macro instructions. GATWR prints the 
message statistics out in the format indicated ander "Programming 
^otes." 

LOGON JOHIS 



(process data) 



OSAGE 
Gh7'4R 
GATWP 



SThTkRTk,nYlD 
STATAFEA, LENGTH 
SSCHILP^LMGTBSEC 



:an default IfillD to TJBIDl 



MYID 


DC 


C'EJBIDI' 




DC 


X»27» 


lESGTK 


DC 


I»200» 


STJIT^REA 


DC 


200X»00» 


SECHALF 


DC 


2oax»oo» 


L2IGTHSEC 


DC 


I»200" 



End of user ID 

Ud to 400 bytes of statistics 
may be recorded in the user area 



BS Al'T ~~ Giv e User C oiitr ol of Att ention Interrupti on s f O) 

The OSAIT macro instruction allows the user to have his own routine 
process attention interruptions from the SYSIM device. 



I Name 

I 



I Operation | Ooeran? 



4- 



-h 



|[ symbol] I USATT 



note : There are no operands- 



I nitia liz ati on: This macro instruction cannot be assembled in a privi- 
leged module unless the most recently issued DCLASS macro instruction in 
the asseably specified USER (see Appendix H) or if the DCLASS ootion is 
USER by default. 

Proqraaniinq Notes: !rhe user must first issue the SAEC and SIR macro in- 
structions to establish the routine that is to process attention inter- 
ruptions. He then issues the USATT macro instruction to disable the 
svstem attention interruption-handling routine, and all subsequent at- 
tention interruptions are processed by the user-specified routine. How- 
ever, if no routine has beer established, the attention interruption is 
lost and the user may not be able to reenter his program . 

Once the user gains control of attention interruptions by issuing a 
OSATT macro instruction, control can be returned to the system by using 
a CLATl, EXIT, CLIC, CLIP, ^AUSE, or COHfA^D macro instructions. If the 
user program issues a CLIC, CLIP, PAOSE, or COHMAHD macro instruction, 
the system regains control of attention interruptions until a RUN com- 
mand (without an operand) is issued. When a CLATT or EXIT macro in- 
struction gives control of attention interruptions to the system, issu- 
ing a BUN command does not automatically return control of interruptions 
to the user- In this case, he can only regain control by issuing anoth- 
er USATI macro instruction in this program. 

If the SAEC macro instruction is used to set up user control of at- 
tention interruptions, the BCB parameter must be specified as SYSINDCB. 
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I If a user is using OSATT to kandle attentions^ the attention handling 
I routine must include a TCNTRL TYPE=RESTART (see Appendix S) macro, or 
I the user's default for the implicit operand ITTHMODE must be OLD; if 
I not, then a terminal lockout will occur (see Appendix I) - 

VC CW — Define a Virtual Channel Coamand W ord ( 0} 

The VCCW macro instruction (for the lORSQ facilitf) aenerates a doub- 
lewordr the virtual channel command word, that contains the proper in- 
formation to inform the lOHEQ macro instruction of the I/O activity 
requested . 

f— 1 1 ^ 1 

IName f Operation lOoerand f 

I , 1 , 

|[ symbol ]| VCCW Icommand code, data address, count f 

I I |[ ,(flag,[SIL][ ,SKP]) ] I 

I I I ^ r 



command code 

specifies the hexadecimal command code. This expression's value i? 
placed, right-aligned, in byte 1 of the VCCW ioubleword. 

Specified as: An absolute expression that specifies the hexadecim- 
al coamand code, or the code itself enclosed in apostroDhas. '''he 
codes are: 

Hexadecimal 

Comiaand Cod e Command Code 

WRITE 01 

R2AD 02 

NOP 03 

SE!«SE 04 

TIC 08 

EEADBK OC 

data address 

specifies the data address (see the Programming Motes) of the VCCW 
to be generated (one word) - 

Specified as : A relocatable expression. 

count 

specifies the count (see the Proarai.minq liotes) of the VCC* to be 
generated (two bytes) - 

Specified a& : An absolute expression. 

flag 

specifies which flag is to be set in the VCCW to be generated 

Specified as : 

CD - Chain aata flag 

CC - Chain command flag 

sec - Software command chaining flag (see "Procraaiainq Sotes" 

below) 
IOC - lORCB chaining flag 
KCC - Indicates no command chaining 

Default: CC 



SIL 



specifies an additional flag (the suppress length indxcator fiaq) 
to be set in rhe VCCW- 
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Specified as ; SIL 

Default; No additional flag is set. 

SKP 

specifies an additional flag (the skip flag) tc be set in the VCCW. 

Specified as : SKP 

Default ? No additional flag is set. 

Proqramininq Notes ; A virtual channel coromawi wcrd C¥CCIt) is a dotikle- 
word located on a doubleword boundary with this forirat; 

Byte - channel command 
Byte 1 - flag byte 

Bit CD chain data flag 

1 CC chain coiranand flag 

2 SIL suppress length indicator flag 

3 SKP skip flag 

U sec software cowiDaiwI chaining flag 

5 IOC lORCB chaining flag^ 

6 Reserved 

7 Reserved 

Bytes 2-3 binary count field of instruction 
Bytes ^-7 address in virtual storage 

Generally, each STAR^T I/O instruction issued by a user causes one I/O 
operation to be executed. The one I/O operation can consist of one 
¥CCW, or a list of VCCWs chained together by the chaining data or chain*- 
ing cororoand flag bits. 

When chaining data, one START I/O instruction executes a list of 
¥CCHs that are chained together by the CD flag bit. The channel coiranand 
in the first VCOf is executed and the data being processed is placed in 
storage under control of all of the remaining VCCWs in the chained list. 
The command codes in the remaining VCCWs are ignored. 

liien chaining commands, one START I/O instruction is used to execute 
a list of VCCWs chained together by the CC flag bit. Each VCCW in the 
list has a command code that is used to control a different channel op* 
eration on the same device. The command codes that are chained need not 
be the same. For instance, it is possible to do a write-backspace-read 
combination with a magnetic tape unit by chaining commands with three 
¥CCWs. A single START I/O instruction will execute all three canmands 
as one I/O operation. During command chaining, an I/O interruption does 
not occur at the end of each VCCW executed. When the last command in 
the chain has been executed, an I/O interruption occurs. 

Although I/O interruptions normally occur at the end of the I/O oper- 
ation (that is, whether single or chained VCCI% operations), the software 
command chain bit (SCO can be set in a VCCW within a chained list of 
VCCWs to cause an I/O interruption prior to the end cf the I/O opera- 
tion. Mien a VCCW is fetched with its SCC bit set, the system receives 
an I/O interruption as soon as it can be accepted, regardless of whether 
or not the VCCW with the SCC bit set has completed its execution. If it 
has not yet been completed, execution of the VCCW list resumes with that 
VCCW; if it has been completed, execution of the list resumes with the 
next sequential VCCW. The software command chain provides a user with a 



^See "Programming Notes", under "lORlQ. " 
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convenient way of noting the progress of an I/O operation i<ihen coirroand 
chaining is being employed. 

J^n I/O request involving a sirall amount of data iray use the data 
buffer in the lORCBj this is called nonbuffered lOREQ . I/O requests 
Csuch as to read a card deck) that require longer data areas obtain buf- 
fers to contain the dataj this is called buffered ICREQ . 

J^ list of VCCWs generated 1:^ use of the VCCW macro instruction may be 
used to inform the ICREC macro instruction what I/O activity is 
requested - 

Ihe VCCW list of a program that enters lORIQ through the nonprivi- 
leged entry point must not refer tc pages of different protection 
classes I if lORCB chaining is in effect Cif the IOC bit is on in cne of 
the VCCWs of each of the chained lists but the last) , then all pages re- 
ferred to by all of the lists must have the same protection class.. 

Restr ictions : The VCCW list must conform to the following rules: 

1. If any VCCW in the VCCW list has the SCC flag set, 

a. The last instruction to be executed must be the last instruc- 
tion in the VCCW list. This is accomplished by having this in- 
struction the only instruction in the list other than a TIC 
which does not have a CD, CC, or SCC flag set. 

b. The last instruction in the list must not be a TIC. 

c. Only the last instruction may have the ICC flag set. 

2. If no VCCW in the VCCW list has the SCC flag set, 

a,. An instruction executed in the VCCW list, other than a TIC, 
that does not have the CD or CC flag set is the last instruc- 
tion executed. 

b. The last instruction in the list may have the IOC flag set only 
if it is the last instruction in the list to be executed. 

3. The last instruction in the VCCW list must not have the CD, CC, or 
SCC flag set. 

4. If a VCCW has the CD flag set, the following VCCW need not have the 
same command code. 

5. No VCCW may have a count field of tanless it is a TIC. 

6. The address of a VCCW incremented by the VCCW count field raist not 
cross a page boundary. 

7. The entire VCCW list must not refer to more than eight different 
pages of storage. 

8. The VCCW list requests the supervisor to allocate space for execut- 
ing a particular VCCW when an lOREQ macro instruction is issued. 

a. In buffered lORBQ, all commands and data must be contained in 
one lORCB. 

b. In nonbuffered ICREQ, all ccwnmands and page lists must be con- 
tained in the lORCB. 
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9. When lORCB ctiaining is requested, the IOC flag must be set on the 
last ¥CCW of the list (generally a NOP) . This command must be the 
last command in tha list to be executed. 

If there is a guestion as to whether a ?CCW list recruires too large 
f an area, an lOREQ macro instruction may be executed and the return code 

f tested. 

I VSEK D ~ ~ Send Message to A n other Ta s k (P) 

I The VSEND macro instruction sends information to another task. 



I 1 1 

f IMame JOperation f Operand 



f |[syrfibol]f¥SE!fD | 

I I L 



I Kote: There are no operands. 

I Execution: I'he S?C 240 resulting from a ?SEND macro instruction roust be 
f embedded in a message control block (MCB) and be the subject of an 
I EXBCDTE irstruction. 

I The receiving task is alerted to the aessage by a task-external in- 

f terruption. ^^hen the eicternal interruption is accepted, the resident 

I supervisor moves the KCa into the recipient task's ISA, No more than 

f 2040 bytes can be transiiitted . If the receiving task^s intertask mes- 

f sage flag (TSIFB) is on, it does not wish to receive messages. If the 

I sending task^s identification indicates that it belongs to the system 

I operator or the batch monitor, the receiving task gets the message (that 

I is, rhe pending task-external interruption) in any event. If the sender 

\ is neither the batch monitor nor the syste*!! operator and the receiver's 

f intertask message flag is 1, register 15 is set to 4, telling the sender 

I that his aessage was not accepted- If the recipient task cannot be 

f touni, reoxster 15 is set to 0. If the message is sent, register 15 is 

f set to 3- If and when the message is acceoted by the recipient task, 

I and if the reply flag in the senders HCB is on, the complete bit in the 

I message event control block pointed to ly the sender's MCB xs S9t to 1. 

I Erar.ir-.le ; sappose you want to send the message »THIS IS A TEST* to a 
I task whose task identification is 1273. You night write: 

AKI 

!^CB DS OD BOOBLE WORL- BOO^DAHI 

NOHBER OF DOl)BLEWOED:> OF MESSAGE TEXT 
FLAG BITE 
I DC X»00» REIURN CODE FOR PECB 

I DC X"00" «!FSSAGF CODE 

I nonprivileaed prograis = 0-127 

f I3r orivileged Drograias = 128-236 

I installation privileger[ 

I procrrams = 237-255 

OUH TUSK ID 
I DC xn273» fASK ID OF RECIPIENT 

I DC A (ECS) IDDP 0^ HS3SA5E ^V2!fT CONTROL BLOCK; 

IF 110 MFCB IS BUILT IHTO THE ISSUING 
PROGRar, IFIS FIELD WOULD BE A (0) . 
IS A 1FST.» 
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sx 


0,:iCb+4 


B 


UPUPAfc'AY 


DS 


OD 


DC 


X ■ 2 • 


DC 


x«oo» 


DC 


x»oo» 


DC 


X"00» 



VSE!JD 




DC 


KiQi 


DC 


X»123t » 


DC 


Xn273» 


DC 


A (ECS) 


DC 


CLVS'THIS 
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WRITE — (VISAtt) Write a Selected Record (S) 

The wRITE macro instriictioii (for VISAM) moves a selectei record from 
a user-specified area to an outoat butfer. The sysreM then includes the 
record in the output data set^ either by key or retrieval address- This 
macro instruction may b-^ usel to update a record or add to the data set. 
When the write operation is completed, orocessing of the user's T>roaram 
continues. 

Standard forii: 



f^ame | Operation f Operand 
-4— — +- 



I [ symbol TflSITF | decb naaie^tyoe ,dcb address, work area a idress , 

I f ^ record key 



-L 



and £-f orin : 



1 , 

Wame | Operation f Operand 



[ symbol ]| WR±TH | decb name, type, [ deb address },[ work area address], 
I |[,recor? key },KF= CL|E) 



Note: K symbol is reguired in the name field of the L-form. If an 
operand is not specified ir the L-form, it must be specif ie^ ip the cor- 
responding E-form of the macro instruction. 

decb name 

specifies the name to be assigned to the data event control block 
(DECB) constructed as part of the expansion of this macro instruc- 
tion. (Refer to Appendix B, Figure 13 for an illustration of the 
DECB.) 

Specified a s: A svmbol (one to eiqht alphameric characters, the 
first of which must be alohabetic) ; in the E-form only, also in 
register notation (1 only). 

type 

specifies the type of WHITE operation . 



Specified as : One of the following codes: 
KR - WRITE replace by retrieval address* 

' " ig 
KS - WRITE replace by key 



r -lor updatmc 



KT - WRITE a record with a new key -for adding a record 

deb address 

specifies the address of the data control block opened for the data 
set being processed. 

Specifie d as: In the standard and L-forro, as a relocatable expres- 
sion; in -the standard and E-forE, also in register notation; in the 
E-fora only, also as an RX address. 

work area address 

specifies the address of the user's work area from which the record 
is to be written. It is the user's responsibility 1:0 place the 
record key in the work area before issuing this macro instruction. 
The address of this record key is specified in the record key 
operand. 
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Spec iti ed_„ as : See the acb address oparand. 

record hey 

specifies the address of the field containing either: 

the recoru key, the length of which is indicated in the data con- 
trol block, or 

a retrieval address, a four-byte field on a full word boundary, 
originally obtained from DCBLPa field of the DCB. 

Spec ifie d as; See the deb address operand. 

In itia li zation : If this laacro instruction is to be executed in a privi- 
leged module, the most recently issued DCL1\SS macro instruction in the 
assembly must have specified PRIVIIEGFD (see Uppendix W) . Also, the 
address of a save area aiust be olaced in register 13 before this macro 
instruction is executed. 

C AliilOil : A WRITE replace by retrieval address (type KH) must not be 
used with a shared data set- 

£3:ceptional conditions resulting from the execution of a WRITE macro 
instruction cause control to be passed to the user's synchronous error 
exit (SYNAD) routine. In this case, the general registers and the ex- 
ceptional condition fields in the data control block are set as shown in 

Appendixes B and F. 

^roq raoiai inq Notes: itBITE releases any page-level interlocks set for the 
data se-L as a result of executing macro instructions referring to the 
same data control block. Eules for sharing VISAH data sets are given in 
Appendix K. 

L- and S - ForFi Ose : The L-form macro instruction results in a nacro 
expansion consisting only of a parameter list (DECB) . The format of the 
DECS is described in Appendix B- 

The L-form macro instruction results in a macro expansion consisting 
of only executable instructions. The ^-form macro instruction uses the 
DECB built for it by the L-form macro instruction. Only !iF=E should be 
written for the fF ooerand in the E-form, because it is the DFCB symbol 
which nases the parameter list of the L-forai. Any E-form parameter 
replaces the corresponding parameter in the DECB. 



WH IT E — (BSAM) Wri t e a Block fS) 

The WRITE macro instruction (for BSRF) writes a block of data from 
virtual storage to a physical sequential data set. To allow the I/O op- 
eration to be overlapped with processing, the WHITE macro instruction 
returns control to the user's program before the output operation is 
complete - 
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Standard form: 



I 1 1 

fName JOperation ^Operand 



f[symbol)f WRITE | decb name^SF^dcb address, work area address, length 

I i 1 ^ ^ 



and E-form: 



I 1 1 ^ 

IHame | Operation f Operand 

I , j.-_ ^ 

|[ syinbol]|WRITE fdecb name, SF, [deb address ],[ work area address] 

I I f[ ,length],f!F= CUE} 

I i I ^ 



SF 



Mote: Jl symbol is required in the name field of the L-form. Any 
operand that is omitted from the L-form must be supplied with the E-forra 
of the macro instruction - 

decb 

specifies the name to be assigned to the data event control block 
(DECB) constructed as a oart of the expansion of this nacro in- 
surnction. (Refer to Appendix B, Figure 18 for an illustration of 
the DECB.) 

Specified as : A symbol {one ^o eight alphameric characters, the 
first of which sust be alphabetic); in the E-forsi only, also in 
register notation (1 only). 

specifies sequential forward writing of the block as part of the 
data set. 

S pecifi ed as : SF 

deb address 

specifies the address of the data control block opened for the data 
set being processed. 

Specified as : In the standard and L-form, as a relocatable expres- 
sion; in the standard and E~form, also in register notation (2 
I through 12) ; in the E-form only, also as an RX address. 

work area aidress 

specifies the address of the area in virtual storage that contains 
the block of data to be written. Ihe user must construct the 
record-length information in front of each block of format-? 
records - 

Specified as : See the first operand. 

length 

specifies, ior format -U records, the number ot bytes to be trans- 
I mitted. If this parameter is specified for foreat-F or format-V 
records, it is ignored. ior format-I blocks, the lenath value is 
obtained from the DCB3LF field of the data control block. For 
fornat-? blocks the length value is obtained fron the first tvo 
bytes of the output area (LL) . 

Spec ifie d ^ as: »S», in which case the aaximum block lenath for the 
data set is used, as specified in the data control block; as an 
absolute expression; in the standard ar.d E-form, in reaister nota- 
tion (2 through 12) . 

Initialization : If this macro instruction is to be executed ii* a orivi - 
leged module, the ir.ost recently issued bCIJlSS aacro instruction in the 

assembly aust have specif ie^l IT'IVILEGED (see ?>ii>pendix F) . lilso, the 
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address of a save area must be placed in register 13 before this macro 
instruction is executed. 

CAUTIOM: Abnormal termination occurs if: 

1 . A WHITE macro instruction is issued with record length longer than 
a track, unless track overflow is specified in the DCB macro 
instruction - 

2. The data control block specified is not validly opened. 

3. The DBCB specified is already in use by a previous BEAD or WRITE 
macro instruction; that is, it has not been checked. 

4. An attempt is made to issue a WRITE macro instruction, causing the 
number of unchecked PSAB and WPITE macro instrucxions to exceed, the 
DC£NC2 parameter in the data control block. 

5. An attempt is made to write on a data set ooened for IMPOT or 

RDBACK. 

6. An attempt is made to write on a file-protected tape when the data 
set was opened with BIS?=OLD. 

Programming Motes : The iRITE macro instruction returns control before 
actual transfliission of data is completed. To determine whether a write 
operation has been completec', the CHECK macro instruction must be issued 
for the DECB for the WRITE operation. The DECS employed for the write 
operation and the virtual storaoe the block occupies must not be altered 
or used until the ChECK macro instruction is issued for that DFCB. 

If a track selected by a WRITK macro instruction is flagged as defec- 
tive, an alternate track ir automatically used. For any device, the op- 
erator is liOtified automatically if any intervention is reguired to com- 
plete the operation. 

f If the data set has been opened for UPDAT (see the OPEM macro) , the 
following considerations apply. 

• The aRITE macro instruction returns a block to a physical seouential 

data sat residing on a direct access device. The data set must be 
opened with the UPDAT option. Only the most recently read bloch can 
be undated and returned. 

• The update mode is provi'^ei ocly for data sets on direct access 
ievices. Although it is not necessary to update and return each 
block, the seguence of operations for those blocks that are updated 

ijust Le: 



LELD Block 1 



CHiiCK Await completion of read 



update block in storage 



WRITE Block A 



CHECK Await completion of write 

ThuSt only the block last read^ or its replaceirentt can be returned 
to the data set. Two READ macro instructions can be issued without 
an intermediate WRITE; this causes the first block to remain 
unchanged on the device, 

Rettirn Data ; After an error causing abnormal terirination^ the eight 
sense bytes used to store information pertaining to disk or tape devices 
are saved in DECB sense bytes through 7. DECB byte 1 should be set to 
X'02' to have these bytes put into the DECB, (See Appendix B, Figure 
18.) 

L~ and E-Form Use ; The L-form macro instruction results in a macro 
expansion consisting of only a parameter list CDECB) . The format of the 
DECB is described in Appendix B, 

The E-form macro instruction uses the DECB built for it by the L-forro 
macro instruction- Only Mf=E should be written for the MF operand in 
the E-form^ because it is the DECB symbol that names the parameter list 
of the L-form. Any E-form parameter replaces the corresponding speci- 
fied optional or required parameter in the DECB, 

Example : The proper use of a WRITE macro instruction for format-^0 rec- 
ords is shown. A data event control block is constructed as part of the 
in-line macro expansion. A WRITE operation is to be performed frc^ AREA 
to the data set defined hf DCBOUT. Eight-hundred data bytes are to be 
transmitted for a format-U record (for formats-V or -F, the length pa- 
rameter woxald be ignored) • 

EXl WRITE ADECB^SF,DCECUT,AREA^800 

WT — Write a Data Set on Tape for Cff-Line Printing (S) 

Ihe WT macro instruction edits arwi writes the specified VSAM or VISAM 
data set on magnetic tape in nonconversational mode for subsequent off- 
line printing and, optionally, erases it from the catalog when writing 
is finished. The output is written on 9-track tape in odd parity with 
standard OS, OS/VS labels. Each input data set record is written on 
tape in proper format for off-line printing, as a logical record or as a 
print line; records are blocked, if requested. The maximum blocked rec- 
ord length is 32,767 bytes. 

Standard form: 

I Name | Operation | Operand f 

^address of operand string 
■data set name l,data set name 2, 
I [volume number], [blocking factor 1, 
( [starting byte] , [ending byte] 
J [,rEDIT 1 ] [,{ERASE|¥|K>] • 
f i skips , [h] , [lines] , [P] j 
.-.i-^ 1 . 
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Ir-form Csee "C^erand Strings* in Part II, Section 1>: 

g. ^ . ^ ^ ^ . ^ ^ — ^ 

I Faroe | Operation | Operand \ 



•data set name l,data set naire 2, 
(vcluice number] , [blocking factor 1, 
[starting byte] , tending byte] 
t , f EEITI skips , CH] , Ilines] , CP3 } 3 
C,{1EASE|Y|N1]« ,MF=L 



E-form Csee ••Operand Strings'* in Part II, Section 1): 



JNaroe j Operation! Operand ( 

l- -j. ^ 1 

I [symbol] |I^T jaddress of operand string ,MI= CE, list) | 

address of operand string 

specifies the address of the first operand in the operand string. 

Specified as ; Register notation C2 through 12) or a relocatable 
expression. Note that the operand string can also be specified in 
the macro operand as a character string ^iclosed in parentheses, as 
shown. 

data set name 1 

specifies the name of the data set to be written on tape in print 
format. The data set name either must preiriously have been defined 
by a EBEF macro instruction or command, or must be in the catalog. 

Specified, as ; The fully qualified name of a nonpartitioned data 
set or a nonpartitioned generation of a generaticn data group Ci- 
dentified by absolute generation name or relative generation 
number). 

data set name 2 

specifies the data set name under which the data set is to be cata- 
loged as it resides on the output tape. The user roust specify the 
name or the task will be abnormally terminated- 

Specified as : The fully qualified name of a nonpartitioned data 
set or a nonpartitioned generation of a generation data group Ci- 
dentified by absolute generation name or relative generation 
number ) . 

volume number 

specifies the volume ID number of the output tape. 

Specified as ; One to six alphameric characters. 

Default ; A scratch tape is used. 

blocking factor 

specifies the blocking factor of the output tape. 

Specified as ; A one- to three-digit number? the maximum blocking 
factor permitted is 246. 

Default s 30 

starting byte 

specifies the byte number at which tape writing is to start for 
each data set logical record. 

21*0 



Specified as : A one- to six-diait n amber. 

Default : Uritina starts with tLe first block, of each logical 
record . 

ending oyte 

specifies the b^te Rumber at which printing is to stop for each 
data ser record. rhis ani byte is written. 

Specifie d as: A one- to six-'ligii: number - 

Default: WritiBq continties 1:0 the last byte of each looical recor^^ 
or until the printer line lenath is reached^ whichever occurs 
first. 

EDIT 

indicates that the line spacing is controlled hv a control charact- 
er in the first byte of each data set logical record. This control 
character is user-supplied and may be in ASCII or machine cole,, but 
must be in the same code throughout the data set (Refer to Appendix 
D.) 

skips 

specifies the nuober of lines to be skipped between records. 

S£ec if ie d__ as : 

1 - indicates skip 1 line 

2 - indicates skip 2 lines 

3 - indicates skip 3 lines 

Default : 1 

H 

specifies that the first locrical record of the data set is to be 
repeated on each print page as a header line. The first 132 bytes 
or the first record, whichever is smaller, is to be used as the 
header - 

Sp ecifi ed, as : H 

Default : The first record is not repeated. 

lines 

specifies the number of lines to be printed on a paae. The Eaximua 
number of lines per page is determined by the printer foroi used for 
the off-line printing of the data set. If not specified, S^ lines 
are printed on each page. 

Spe cified as; A one- or two-digit number. 

Default: 5^4 

F 

specifies that page numbering is to be performed. 

Specified as : P 

Default: Ho page numbering is performed. 

ERASE|Y|N 

specifies the disposition of the cataloged data set after the tape- 
writing operation is complete. 
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SP ecitied as : 

EaasF or I - erase the cataloge-i data set after the tape-¥ritiBg 
operation is cor»Dlete. 
N - do not erase the cataloga-l data set. 

Dexaolt: *i 



1^^^- If ERASE or Y is soecified for a share! data set that is 
currently being used by another user, a diaonO'Stic message is is- 
sued and the data set is not erasei . 

Iriit ializat ion : If this macro instruction is to be executed in a orivi- 
leaed module, the most recently issu€-d DCLAS5 nacro instruction in the 
assembly luust have specified P^IVILEGEB (see Appendix M) . AlsO', the 
address of a save area liust be placed in register 13 before this macro 
instruction is executed. 

Prograaainq Motes : When the user executes a KT macro instruction for a 
data set defined in his task, the data set is released and disconnected 
froiTi rhe user's task- The WT macro instruction orocesses data sets that 
were createi by usinq either the virtual sequential or virtual index 
seguential access iiethod . The tape data set is created by using the 
basic se*Tii^ntial access aethod. This output tape is written in odd 
parity '-fink stanciard OS, OS/VS Labels. The data set nust be in the 
catalog- If it is not cataloged the user's task is terminated. The 
Ei'vASS option can be used, to erase the data set after writing is 
coapletciid - 

Zl a data set to be ^-ritten on taoe was created via the DATA comiaand, 
the firs'c byte of each record contains an indicator for the origin of 
the record. Unless the starting byte operand is specified, this byte is 
written as oart of the record upon issuance of the WT macro instruction. 
In such a case, if the record '*as originally entered through a card 
reaier, the inlicator byte will be written as a C. If it was entered 
through a terminal, the byte will be written as a blank character. When 
the starting byte operand is specified as 2 or greater, the indicator 
byte is bypassed and is not included as part of the written record. 

ilG more than one print line can be written from a single data set 
record. It a read error occurs, the record in guestion is written in 

hexadecimal form on SYSOUT. 

Feturn Daxa: At completion of execution of the ¥T macro instruction, 
register 1 contains the address of the batch seouence number assigned to 
the nonconversational task established by this macro instruction; the 
low-order tyte of register 15 contains one of the codes given below. 

Code Significance 

WT reauest was accepted. 

All other codes Register 15 contains a two byte system raessage 

number- 

Examples : In i£Xl, the operand string is presented as a character 
string. In EX?, a symbolic address designates the address of the 
operand string. 

EXl I^T ■OLDKAM'e,MFlNAME» 

EX2 WT TAPTAG 

Since EX2 is given as an address, the user has provided the operand 
string at location TAPTAG. When the macro instruction is executed, the 
necessary alphameric characters must be available in the string. 
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WTL — Write to Log CS) 

The WTL macro instruction writes a message in the system log. If 
specified in the system operator's user profile, the message is also 
written on the main operator's console. 

Standard and L-form: 

[Naire | Operation | Operand | 

I.- ^.«+ ^ 1 

I Isymboll I WTL | 'message text' [ ,MF=L] | 

Note ; h symbol is required in the name field of the L-form. If the MF 
operand is omitted, MF=I is assumed. 

E-f orm: 



[Name | Operation | Operand | 

I [symbol] I WTL |MF=(E,list) | 

message text 

specifies the message to be inserted in the system log and, if 
specified in the system operator's profile, written on the main 
operator's console. The message can include commas, blanks, and 
apostrophes, as in a character constant. The maximum message 
length is 255 bytes, including the required enclosing apostrophes. 

Specified as s The text of the message itself, enclosed in 
apostrophes. 

Initialization s If this macro instruction is to be executed in a privi- 
leged module, the most recently issued DCLISS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M). Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

Prograirminq Notes s Parameter list use by the WTL macro instruction is 
not standard: register 1 contains the address of the message (rather 
than of an area that contains the address of the message) . Refer to the 
second example tinder the WTO macro instruction. 

Return Data ; At completion of execution of the WTL macro instruction, 
the low-order byte of register 15 contains one of the following codes; 

Code Significance 

00 Successful completion 

0^ Attention mterruption 

OC Invalid message length? no message sent. 

Example ; The message ALL ON is to be sent t^ the operator and entered 
in the system log. 

EXl WTL "ALL OM' 



WTO — Write to Operator (S> 

The WTO macro instruction writes a message on the main operator's 
console. 



Part 2: Macro Instructions 2«l3 



standard and L-formj 

J ^ , — ^,j_^ . .^. _. — ^ — . . ^ — ^ ^ ^ 

I Name |Operation| Operand j 

I [symbol] |lfTO }■ message text* C,MF=L] | 

Note: h symbol is required in the name field of the L-forro, If the MF 
operand is omitted, the standard form is assuraed. 

E-form: 

y. .^ , — ^ . — ^ -. — « , ^ , . — ^ 

I Hame | C^eration | Operand | 

^„_^. — ^4 +^„_ . ^^_„„. ^^ 

I Csymboll |WTO |MF=CE,list) j 

message text 

specifies the message to be written on the operator's console. The 
n^ssage can include commas, blanks, and apostrophes as in a 
character constant. The maximum message length is 255 bytes. The 
message includes the required enclosing apostrophes. 

Specified as ; The message itself, enclosed in apostrophes^. 

Initialization ; If this macro instruction is tc be executed in a privi- 
leged module, the most recently issued ECL^SS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix M). Also, the 
address of a save area must be placed in register 13 before this macro 
instruction is executed. 

Programming Notes ; Parameter list use by the WTO macro instruction is 
not standard: register 1 contains the address of the message (rather 
than of an area that contains the address of the message). See the 
second example below. 

Return Data ; At completion of execution of the WTO macro instruction, 
the low-order byte of register 15 contciins one of the following hexade- 
cimal codes; 

Code Significance 

00 Successful completion 

0^ Attention interruption 

OC Invalid message length; no message sent. 

Examples ; In the following example, the message NOW COMPLETE is to be 
sent to the operator. 

EXl WTO "New CCMPLFTE* 

The following example illustrates the use of the WTO and WTL parame- 
ter lists necessitated by the nonstandard use of parameter lists involv- 
ed in these macro instructions: 



WTOLEN DC A C L'» WTOTXT ) 

WDOTXT DC C'« MESSAGE TEXT* 



WTO M,F= C E , WTOLEN ) 

WTL MF= C E , WTOLEN ) 

2m 



BTO& — Mrite to Operator with Action Message fS} 

ThB WTOA macro instruction writes Operator Action messages (messages 
requiring some type of action from the operator) on the main operator's 
console . 

Standard and L-form: 

I 1 1 ^ ^ 1 

Jliame | Operation | Operand f 

I 1 1 -I 

|[syiibol]|WTOA I "message text»[,MF=L] f 

I I I ^ ^ I 

Hote: A symbol is reguired in the name field of the L-form. If the ^¥ 
operand is oaitted^ the standard form is assumed. 

E-form: 

^ J, J J 

fUame (OoerationlOperand | 

I 1 \— 1 

f[symbol]|WTOA f!!F= (Enlist) f 
I I I 1 

message text 

specifies the message to be written on the operator's console- The 
message can include special characters such as commas, auestior 
marks, and apostrophes. The maximum message length, including the 
required enclosing apostrophes, is 255 bytes. 

Specified as : The messaae itself, enclosed in apostrophes - 

The message, when displayed on the operator's console, is preceded by 
a series of three pointers (minus sign followed by greater-taan sign) 
which appear as three arrows pointing from tne margin towards xhe 

message. 

Initialization : If this macro instruction is to be 'executed in a privi- 
leged module, the most recently issued DCLASS macro instruction in the 
assembly must have specified PRIVILEGED (see Appendix H) . Also, the 
address of a save area must be placed in register 12 before this macro 
instruction is executed. 

P rogramming notes : Parameter list use by the WTO A macro instruction is 
not standard: register 1 contains the address of the message (rather 
than of an area that contains the address of the message) . 

Re turn Dai:a ; At completion of execution or the fcTOA macro instruction, 
the low-order byte of register 15 contains one of the following hexade- 
cimal codes: 

Code Significance 

00 Successful completion 

04 Attention interruotion 

DC Invalid aessage lenath; no laessaoe sent 

Example : In the following example, the message ¥.EkT IS ADHIMISTBATGH* S 
EXTE^ISIOJ NOHBEK? is to be sent to the operator. 

EXl WTOA 'WBAT IS AOFItJIS IHATOB • • S EXTE'ISIOS ^UFBFP.?' 

This example will appear en the operator's console as: 

->->-> MHAT IS ADf IHISTRATOE»S EXTE^iSIOJ ^OfBTR? 

Hote: The pointers are provide-'^ by the ^••TOA oacro ir^smiction . 
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WIOH — Write to Operator w ith Reply fS) 

The WTOB macro instruction writes a message on the system operator 
console ana enables the system operator's reply to be transmitted to the 
program issuing the macro instruction. No further processing of the 
program occurs until the operator replies. 

Standard form: 



IHame (Operation f Operand 
I \ f" 



|[ symbol ]|WTOP | 'message text • ^reply area address, reply length 

-I 



L-f orm : 



fHame f Operation (Operanc^ 

I J— f- 



fsymbol |WTOR Mmessage text», [reply area address] 
I \ I [ ,reply length ],KP=L 



Note : A symbol is required in the name field of the L-form. 



E-form : 



fSame (Operation (Operand 
I- ! h-^ 



f[ symbol ] I WTOE f[ reply area address ][, reply length ]^HF= (E, list) f 
I I I '. 1 

l^t^* A^y operand that is omitted trow the L-form must be supplied with 

the S-form of the macro instruction. 

message xext 

specifies the message to be written on the console- The Miessage 
can include commas, blan}ts, and apostrophes as in a cnaracter con- 
stant. The maximum message lenoth is determined at system genera- 
tion. This length must not exceed the Physical line length on the 
console output deyice or 253 characters, whichever is less. The 
fiiessaae appearina on the console 3oe£ not include the enclosing 
apostrophes . 

Specified as: The text: of the message itself, enclosed if: 

apostrophes - 

reply area address 

specifies the ac! dress of an area into which the message reply text 

should be placed. 

Spe cifie d as: In tiie standard and L-form, as a relocatable expres- 
sion; in the standard and F-f orm , also in register notation (2 
through 12) ; in the E-forin only, also as an BX address. 

rC'ply i-:ingth 

sDecifies the lenath, in bytes, of ths reply text- The value Kust 
not exceed 2 55- 

Specified as: An absolute expression; in standard and E-form, also 
in register notation (2 through 12} - The value specified may not 
exceed 255. 
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Initia l izat ion: If this macro instruction is to be executed in a Drivi- 
leged module the aost recently issued BCLASS macro in sr ruction xn the 
assembly aust have Specif iei PRIVILEGED (see Appendix !^.) Also, the 
address of a save area iaast be placed in register 13 Iiefore this macro 
instruction is executed. 

Prog raiaminq No tes: At completion of ei^ecution of the WTOE ciacro in- 
struction^ the low-order byte of register 15 contains one of the follow- 
ing hexadecioial codes: 

Code Significanc e 
00 Successful completion 
4 Attention interruption 

DC Invalid message length; no p.essaae sent. 
f 10 Reply length greacer than specified maziiLum rei>ly length: 

reoly was received, but only the maximum number of characters 
is in the reply area. 

Example : The message 13 B. E. SMITH JOINED? is written on the opera- 
tor's console. The expected reply is tri.ree bytes long ("yes" or "co") 
and Mill be stored at location ALPHA. 

EX1 WiOF 'IS 5. ^. SMITH JOIIv^SD? • , ALpH.^ , 3 

I XTRTK — Extract Accumulated CPU Time (O) 

I The XTRTM macro instruction enables vou to extract and eza;iiine the 
I total CPU time used by your task. 



i 1 1 ■ 

I IName (Operation (Operand 

I 1 ! 

f f[symbol]fXTRTM \ 

i I 1 



I ^ Qte : There are no operands. 

I Execution: The address of the task's XTSI is obtained by the SVC oro- 
f cessor. The accumulated tiae is computed by subtracting the current 
I timer value from the last time slice value and addina the accumulated 
I time value to the difference. 

I Return Data : The total accumulated CPU time (in milliseconds) of the 
I issuing task is computed and returned to the task in register 1. 

I Example : If you want to extract your task's accumulated time, you miaht 
write: 

I TIHE XTITM 
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M£llHI_iii. EXIT LIST (EXIST) 



The T.1LZ7- operaai of the DCS macro in.Ftruction say be specified only 
wnen using 3SA% or QSKfi data orqanixation . 

The exit list consists or a series of co.Ies and aidresses that inforE 
the syst.c:m or the location of a iiser-sapplied exit. 

Each entry in the list consists of three contiguoiis words aligned on 
tullwcrd boandaries. 

1 byte 



Worii 1 



Ss^ord 3 



1 code 


f 
1 
f 




Unused | 


1 V-con 


of 


routine 




1 H-con 


of 


routine 





-k bytes- 



Entries do not have to be in order by code. To irdicate the last 
entry in the exit list, the hiah-order bit of the byte containing the 
code is turned on. Since there are only five codes, the list should 
contain a aaximum of five entries . 

If an exit routine is in the same assembly module as the exit list, 
two A-type address constants should be coded for words 2 and 3 of the 
entry. 



I Code (hex) | 



Keanina 



00 
01 

02 
01* 
0> 
07 

oa 

6X 



I Entry i0nored, i.e., not active 

I 

fUser routine to process user header labels 

\ 

I User routine to create user header labels 

I 

IDser routine to create user trailer labels 

I 

I User DCB exit routine 

I 

ICser routine to handle input end-of -volume 

I 

f User routine to handle output end-of-volume 

I 

I Signal last entry in list, where X is 0-8 representing 

fOO-Od codes above 
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r — 



OPEN 

INPUT 

OUTPUT 

UPDAT 

INOUT 

OUTIN 

RDBACK 



-r 



TRAILER LABELS^ 
j. 



HEADER LABELS^ 



end-of-voltune 



INPUT 
OUTPUT 
UPDAT 
INOUT 

OUTIN 

RDBACK 



(READ) 
(WRITE) 
(READ) 
(WRITE) 



h 



FEOV - CLOSE 



(READ) 
(WRITE 
(READ) 
(WRITE) 



Exit 03 
INPUT 



1- 



X 
X 



INPUT 
OUTPUT 
UPDAT 
INOUT 

OUTIN 

RDEACK 

^Exit nol: taken if 5 (1) current volume in process is last volume, or 

(2) data set is to be closed 
^If last I/O operation was backward, user header label routine is 

invoked for trailer label processing and user trailer label routine 

is invoked for header label processing 



Exit 04 
OUTPUT 



+™ 



Exit 01 
INPUT 



■H 



X 
X 



4„ 



x^ 

x^ 
x^ 

x^ 

x^ 



Exit 02 
OUTPUT 

1 



-i 



X^ 



X^ 



x^ 



— — I 

x^ 
x^ 
x^ 

x^ 

x^ 
x^ 



Figure 17, Conditions upon exit -- routine entries 



COMMON CONDITIONS ON KiTRANCE TO EXIT ROUTINES 

On entrance to any user exit routine, register 13 will contain the 
address of a save area which may be used in linking to other routines • 
The 19th word of the save area will contain the R-con specified in the 
exit list. The contents of the rest of the save area will be unpre- 
dictable* Register 14 will contain a return addressi its contents 
should be restored before issuing the RETURN macro instruction* 
Register 15 will contain the address of the entry point to the exit 
routine and may be changed by the exit routine according to the indi- 
vidual exit routine instructions outlined below. The contents of the 
remaining registers (except for registers and 1 as outlined below) 
will be tinpredictable, 

CAUTION; Type III linkage is used to link to the ncnprivileged user's 
exit routine. The exit routine is restricted to type I linkage in 
linking to other subroutines, and thus cannot issue macro instructions 
that require other types of linkage, such as GATWR and OBEY. 
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REQUIREMENTS FOR INDIVIDUAL TYPES CF EXIT ROUTINE 

Code 01s User Rout:ine to Process User Header Labels 

When this routine is entered, register 1 contains the address of the 
data control block being processed, and register contains the address 
of an 80-byte buffer that contains a user header label. The first four 
bytes of the buffer contain the characters UHLl to UHL8 or UTLl to UTL8 
depending on which of the eight permissible user header labels or 
trailer labels is being processed. To obtain the next label, the user 
issues a RETURN (no operands except RC= are allowed) with a hexadecimal 
04 in the low-order byte of register 15. When the last label is pro- 
cessed, the user issues a RETURN roacro instruction with a hexadecimal 
00 in the low-order byte of register 15. The user may not issue data 
management macro instructions for this data set in this routine. 

Code 02s User Routine to Create User Header labels 

When this routine is entered, register 1 contains the address of the 
data control block being processed? register contains the address of 
an 80- byte buffer in which the user is to biiild a label. The first 
four bytes already contain the characters UHLl to UHL8 depending on 
which of the eight permitted user header labels is being created. 
These four bytes must not be altered. The user places information in 
bytes 4-79. Issuing a RETURN macro instruction, with a hexadecimal 04 
in the low-order byte of register 15, causes the label to be written, 
and requests control to be returned to this routine so another label 
may be created. Issuing a RETURN macro instruction, with a hexadecimal 
00 in the low-order byte of register 15, causes the last label to be 
written, and control is not returned to this routine. The user may not 
issue data management macro instructions to this data set in this 
routine. 

Code 03s User Routine to Process User Trailer Labels 
Same characteristics as Code 01. 

Code 04; User Routine to Create User Trailer Labels 

Same characteristics as Code 02, except the characters UTLl through 
UTL8 are substituted for UHLl through UHL8. 

Code 05s User DCS Exit Routine 

When this routine is entered, register 1 contains the address cf the 
data control block being opened. The user may alter fields in the data 
control block, if desired. To return control to OPEN, the user issues 
a RETURN macro instruction (no operands except RC= are permitted) with 
a hexadecimal code of 00 in the low-order byte of register 15. 

Code 07 s User Routine to Handle Input End-of -Vcluire 
Same characteristics as Code 01, 

Code 08s User Routine to Handle Output End-of-Voluire 

Same characteristics as Code 02, except the characters UTLl through 
UTL8 are substituted for UHLl through UHL8. 
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EXIT-LIST EXAMPLE 

The following is an example of the coding of an exit: list. The exit 
list must be in the same assembly module as the data control block (DCB 
macro instruction) which refers to it. 



APPLE 



DC 


OF ALIG 


DC 


X"02" 


ADCON 


IMPLICIT ,EP=MHDRLAB 


DC 


X*03* 


ADCON 


IMPLICIT ,EP=PHDRLB 


DC 


X'Ol' 


ADCON 


IMPLICIT ,EP=PLABY 


DC 


X'85* 


ADCON 


IMPLICIT ,EP=ALTER 



ALIGN TO FULLWORD BOUNDARY 



The symbolic name of this exit list is APPLE- To use it^ EXLST= 
APPLE must be written in the DCB macro instruction. Note that the 
high-order bit of the hexadecimal code for the last entry is on, indi- 
cating the last entry in the exit list. 
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APPENDIX B: SYNCHRONOUS ERROR EXIT ROUTINE (SYNAD) 



When using BSAM, QSAM, VISAM (either for VISMf data sets or VISMA 
members of VPAM data sets), or lOREQ macro instructions, it is possible 
that errors may result from an attempt to process data; in many cases, 
certain remedial actions are available to the user* 

If desired, a routine may be written for the purpose of receiving 
control from the system when an error occurs. The conditions that 
cause control to be given to the SYNJUD routine are described under each 
macro description. 

The user indicates to the system that a SYNAE routine is supplied by 
writing the keyword parameter SYNAD= in the DCB macro instruction. The 
task is terminated if an error occurs that would normally cause SYNAD 
to be entered and no SYNAD was supplied. 

The following is a list of si:^gested actions to be taken in a SYNAD 
routine: 

!• Issue a RETURN macro instruction, which causes a record to be 
accepted with error ignored (ESAM and C^AM only). 

2. Set flags that are meaningful to the program, 

3', Close the data set. 

4. Resume processing at another point in the data set. 

5. Call another routine- 

6. Terminate the program. 
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Entry To SYNI^D During BSAM or QShM Operations 

If BSAM or QSAM is being used, the contents of the general registers 
upon entry to the SYNAD routine are as follows: 



Usage 



I Register j Bit 

10 thru 31 (Address of data event control block (DECB). 



I 



2 thru 12 



+ 

13 



14 

h- 

15 







Set to 1, if error was caused by a READ macro in- 
struction (for BSAM), or by GET or RELSE macro 
instructions Cfor QSAM) 

Set to 1, if error was caused by a URITE macro 
instruction (for BSAM) , or by PUT, PUTX or TRUNC 
macro instructions (for QSAM) 

Set to 1, if error was caused by a BSP, CNTRL or 
POINT macro instruction (for BSAM) , or by a SETL 
macro instruction (for QSAM) 



5 thru 31 



— f 



Set to 1, if (1) error indicated by bit did not 
prevent reading the block? or (2) if error indi- 
cated by bit 1 occurred during creation of a new 
block 

Set to 1, if request was illogical? e.g,, a POINT 
macro instruction (for BSAM) or a SETL macro in- 
struction (for QSAM) referred to a block not con- 
tained in the data set 



Not used 



(contents that existed before the macro instmic- 
tion was ocecuted) 



-H 



I SYNAD R-con value (for BSAM) , or address of serv- 
|ice routines save area (for QSAM)*^ 

I Return address 
4- 



The address of the entered SYNAD routine 



♦For QSAM the nineteenth word of the save area pointed to by register 
13 contains the PSECT address (R-con) for the SYNAD routine. 



H 



If the BSAM user specifies a SYNAD routine in his DCB, the routine is 
invoked for all errors • BSAM error codes are returned in the one -byte 
field of the DECB, DECID. If the DECID code is less than X"«lO% as many 
retries as wanted may be attempted. If the code is greater than or 
equal to x"40*, but less than X'80% one retry is allowed? if that 
retry results in a code of less than X"*lO*, an unlimited number of 
retries can then be attempted? if the retry results in a code greater 
than or equal to X'80", no further retries are allowed. If the DECID 
code is greater than or equal to X"80", and a retry is attempted, an 
ABEND (compcode 1) occurs. All error conditions that cause I/O retry at 
an alternate path are posted again after they are retried until they are 
successful (DECID=X'00*), or until all paths fail (DECID=X"8X»). For 
some error conditions, the user has control over retry by using the IMSK 
in the DCB. The hexadecimal return codes are: 
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Code Meaning 

04 Unit exception diaring read 

05 Unit exception during read backwards 

06 IMit exception during write 

07 Tape at load point 

08 Disk end of cylinder 
12 Data check 

14 Chaining check 

15 Overrun 

20 Incorrect length for length specified by LRECL, 
BLKSIZE and RECFM of DCB 

21 Incorrect length for length in physical record 
24 Tape data converter check 

30 Error not retried due to DCB IMSK 

40 File protected tape 

42 Device not ready — intervention required 

43 Tape unit non-existent — intervoition required 
46 Control xmlt and/or drive cannot read NZRI tape 

50 Channel control check 

51 Interface control check 

52 Channel data check 

54 Bus out check 

55 Equipment check 

56 Seek check 

57 Missing address marker 
5C SIC failure 

5D Sense failure 

5E Invalid sense information 

60 Program check 

61 Protection check 

62 Command reject (not file protect) 

63 Track condition check 

64 Track overrun 

65 Unexpected end of cylinder 

66 No record found 

67 File protected 
6C Invalid status 

6D CCW specification check 

6E SDA not in CHBSCT 

70 Purged I/O 

71 Reset macro not accepted 
80 No path available 

94 Chaining check — device unavailable 

95 Overrian — device unavailable 

C3 Intervention required — device unavailable 

DO Channel control check -- device unavailable 

Dl Interface control check — device imavailable 

D2 Channel data check — device unavailable 

D4 Bus out check — device unavailable 

D5 Equipment check — device unavailable 

D6 Seek check — device unavailable 

DC SIO failure — device unavailable 

DD Sense failure — device unavailable 

FF Recursive SYNM) exit — device unavailable 

The EXPLAIN command may be used to obtain an explanation of any of the 
above messages i issue the following at the terminal: 

EXPLAIN DECID=xx,CZCRC 

where xx is the DECID code to be explained. 

The DECE begins on a fullword boundary; its format is shown in Figure 
18- 
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I Byte 





1 
4 and 5 
6 and 7 
8 thru 11 
12 thru 15 
16 thru 19 
20 thru 25 

26 

27 
28 and 29 

30 

31 
32 thru 39 
40 thru 47 



Bit I 

I Always set to 



Usage 




1 

2 thru 31 



Completion flagi set to 1 when an I/O event is 
completed 

(Used by the system) 

BSAM flags 

Type field 

Length field 

Data control block address 

Area addresses 

Pointer to status indicators 

(Used by the system) 

Sense byte 

Sense byte 1 

(Used by the system) 

Permanent error flag 

(Used by the system) 

Channel status word 

Sense bytes through 7 

Figure 18. Data event control block (DECB) 

BSAM flags 

indicates whether more than 2 sense bytes are needed. A X"02* in- 
dicates the need for 8 extra sense bytes, which will be used for 
information about disk or tape devices. 

Caution ; If the user is building his own 1-f orro DICB and specifies 
X"02" in byte 1, an 8-byte field must be added to the original 40 
bytes of the DECB. 

Type field 

contains a numeric value representing SF (for READ or WRITE) or SB 
(for READ). 

Length field 

contains a binary number that represents the number of bytes in a 
block, or an indicator that the maximum block size specified in the 
data control block was used. 

Data control block address 

contains the address of the data control block. 

Area address 

specifies the I/O area address. For BShM it contains the address 
of the high-order byte of an area in virtual storage that is the 
object of a forward READ or WRITE? or the address of the low-order 
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byte of an area in storage that is the object cf a backward READ 
operation. 

Pointer to status indicators 

contains the address of the status indicators, which are two bytes 
in the channel status word. If control is passed to the SYNM3 rou- 
tine status information (i.e. , sense byte 1, sense byte 2, and the 
channel status word) is arranged as indicated above. Each of these 
status indicators is described in detail below. 

Channel status word 

is a doubleword illustrated belows 



STORAGE 
PROTECTION 
KEY 



t— 



I 

I CCMimM) 

I ADDRESS 



STATUS 
EYTE 
1 
(unit) 



— ^ — , ^ — -, 

I STATUS 
I EYTE 
I 2 
I (channel) 



— ^^ 



COUNT-FIELD 



J 



The first six bits of sense byte 1 and all bits of status bytes 1 
and 2 are device-independent. Their meaning is as follows: 






-TT- 



'^rt' 



Bit 



I Sense Byte || |Status Byte 1| 
.4 ^^ |. + , I. 4, 



— ^ 



2 

3 

5 



Command reject 

Intervention 

required 

Bus out check 

Equipn^nt 
check 

Data check 

Over run 



Bit 



Status byte 2 



2 
3 

5 
6 



Attention 



Status mod- 
ifier 

Control unit 

end 
Busy 



Channel end 
Device end 
Unit check 






Unit excep- 
tion 

.ji , »j i- 



Bit 







2 
3 

5 
6 



Prog ram- con t ro 11 ed 
interruption 

Incorrect length 



Program check 
Protection check 

Channel data check 

Channel control check 

Interface control 
check 

Chaining check 



Bits 6 and 7 of sense byte and all bits of sense byte 1 are 
device-dependent. Refer to individual publications on specific 

devices for interpretation of these bits. 

sense bytes through 7 

contain information pertaining to READ or liRITE macro instructions 
involving tape or disk devices. Refer to individual publications 
for the specific devices for the number of bytes that are used, and 
for details of the contents of these bytes. 

CAUTION: If any of the bits 4-7 of status byte 2 are on, the system 
cannot recover. Any subsequent I/C operations on the data set result in 
abnormal termination of the task. 
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If the permanent error flag in the data event control block is on^ 
the program must not issue any further I/O operations tc the data set. 

If SINAD is invoked iDecause of SETL only, the DCE address and status 
information in the DECB may be valid. Ml other fields may contain 
undefined information. 

Entry to SYNAD During VISAI4 Operations 

*Ihe SYNAD routine may be entered dxiring VISAM operations (either 
processing of a VISAM data set or a VISAM member of a VPAM data set) . 
The contents of the general registers upon eitry to the SYNAD routine 
are as follows. 

I Register | Usage j 

lAddress of DECB, if error was caused by a READ or WRITE 
I macro instruction. See Table 8 

1 {Address of the data control block 

1^^ ^^ ^ 

2 thru 13 1 (Contents that existed before the iracro instruction was 
[executed) 

li* I Return address 



15 (Address of the entered SYNAD routine 

Additional information concerning the error that may prove useful to 
a SYNAD routine is found in the data control block fields, DCBEXL and 
DCBEX2 (Appaadix F) . 
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APPENDIX C: END OF DATA ADDRESS CEODAD) 



When using data roanageroent services for input: data sets, the exact 
number of records in the input data set need not be knoi^m. When the 
last record of a data set being sequentially processed is accessed, a 
subsequent attempt -to access a record causes the system to transfer con- 
trol to a specified point in the user's prograir. For ESAM the transfer 
is made upon checking the READ macro instruction that requests a block 
after the last block is accessed* For QSAM the transfer is made when 
the user issues a GET macro instruction after all the records in the 
data set have been processed. 

The user indicates to the system where control is desired upon the 
end-of-data condition by writing the keyword parameter EODAD= in the DCB 
macro instruction. The task is terminated if an EODAB routine is not 
supplied and an attempt is made to access a record after the last record 
in the data set. For BSAW, the termination occurs upon issuing the 
CHECK macro instruction for a READ macro instruction issued after the 
last block of a data set is accessed. 

When the end-of-data routine is entered, the general registers are 
set as follows: 

^^ ^ , ^_^ ^_ ^ , ^ , — ^ ^ 

[Register | Usage i 

|.^^ 4 ^ 

I (Not defined) 

I 

1 I Address of data control block 

I 
1 2 thru 12 I (Same as before the routine was entered) 

I 
13 |EODAD R-con value (for BSAM) , or address of service routines] 

[save area (for QSAM)* 

! 
15 lAddr^s of EODAD routine 

♦The nineteenth word of the save area pointed to by register 13 will 
contain the PSECT address (RCON) for the EODAD routine. 

L . . . . ^. ^ J 
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I^PPENDIX Ds CJ^HRIJ^GE CONTROL CliARl^CTERS 



J^ll record formats may optionally include a carriage control charac- 
ter in each logical record. This control character is recognized and 
processed if a data set is being written to a printer or punch. For 
format-F and -U records this character is the first byte of the logical 
record. For forma t-V records it must be the fifth byte of the logical 
record, immediately following the logical record length field. 

Two alternatives are available; i.e., the carriage control character 
may be in machine code or FORTRAN code. If either option is specified 
in the data control block, the character must appear in every record. 



MACHINE CODE 

The user may specify in the data control block that the machine code 
control character is placed in each logical record. The user-supplied 
byte roust contain the bit configuration specifying a write and the de- 
sired carriage or stacker- select operation. Only those commands that 
include a write are permitted; the independeit carriage and stacker 
select operations are excluded. 

The machine code control characters are: 



Function 



l~ 



Byte Value (hexadecimal) 




Write (no automatic space) 

Write and space 1 line after printing 

Write and space 2 lines after printing 

Write and space 3 lines after printing 

Write and skip to channel 1 after printing 

Write and skip to channel 

Write and skip to channel 

Write and skip to channel 

Write and skip to channel 

Write and skip to channel 

Write and skip to channel 

Write and skip to channel 8 after printing 

Write and skip to channel 9 after printing 

Write and skip to channel 10 after printing 

Write and skip to channel 11 after printing 

Write and skip to channel 12 after printing 



after printing 
after printing 
after printing 
after printing 
after printing 
after printing 



h 



Note s To obtain the corresponding carriage-control operations (space 
or skip to channel N) without printing, increase the value of the low- 
order digit by hexadecimal 2. Example: space two lines - 13; skip to 
channel 5 - AB; skip to channel 9 - CB. 



FORTRAN CODE 

The user may choose to specify FORTRAN (formerly called ASA or USAS- 
CII) code rather than machine code. FORTRAN uses the same control 
characters as the American National Standard Code for Inforination 
Exchange, ANSI X3. 4-1968, sometimes referred to as ASCII. The code byte 
must appear in each logical record if this option is chosen, in the po- 
sition defined above. The FORTRAN control character codes are: 
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FUNCTION 



Skip 
Skip 
Skip 
Skip 
Skip 
Skip 
Skip 
Skip 
Skip 
Skip 
Skip 
Skip 
Skip 
Skip 
Skip 
Skip 



no line before printing 

1 line before printing 

2 lines before printing 

3 lines before printing 

to channel 1 before printing 
to channel 2 before printing 
to channel 3 before printing 
to channel 4 before printing 
to channel 5 before printing 
to channel 6 before printing 
to channel 7 before printing 
to channel 8 before printing 
to channel 9 before printing 
to channel 10 before printing 
to channel 11 before printing 
to channel 12 before printing 
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APPENDIX 15 LINKAGE CQHVEHTIONS 



Linkage conventions govern coromtini cation among programs by establish- 
ing a standard that permits easy, efficient, error-free branching and 
linking to a desired program. The following chart summarizes the ele- 
ments required by an assembler program to be both a calling and a called 
program 5 



Entry ^ j 



1 



SAVE routine 
Program statements 






Calling sequence to another program 



J. 

I Program statements 

I RETURN routine 



1 



Entry 
^ 



Exit 



Called Program 
f ] 



I 



Exit- 



H 



Parameter list area 

L . . . - I 



In TSS, all linkage among programs residing in virtual storage con- 
forms to one of the following three convention types: 

• Type I — Between two nonprivileged or between twc privileged 
programs. 

• Type II -- From a nonprivileged to a privileged program. 

• Type III — From a privileged to a nonprivileged program. 

Only the Type I convention is presented in this appendix i Types II 
and III conventions are described in System Proqramirer's Guide . 

Type I linkage conventions include three basic standards to which the 
assembler user must adheres 

1- Utilizing the proper registers in establishing a linkage. 

2. Reserving a save area in the calling program in which the called 
program may save the contents of the calling program registers. 

3. Reserving a parameter area in the calling program, to which the 
called program may refer. 
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Proper Register Use 

TSS has assigned roles to certain registers used in generating a 
linkage. The fimction of each linkage register is illustrated below. 
Note that registers 2 through 12 are not used. 



I General Register | Usage j 

I- + 1 

0^1 iParameter list registers 

I 
13 I Save area register 

I 
1^ (Return register 

I 
15 lEntry point register, return code register 

It is the responsibility of the called program to maintain the integ- 
rity of registers 2-12 so that their contents are the same at exit as 
they were at entry to the called program. It is the calling program's 
responsibility to maintain the floating point registers around a call, 
Registers 0, 1, and 13-15 roust conform to the indicated conventionsi 
when using system services (for example, interruption handling), these 
registers should not be used by the calling program, because their con- 
tents may be destroyed. 

Reserving a Save Area 

Every calling program must reserve an area of storage (save area) in 
which certain registers (that is, those used in the called prograir and 
those used in the linkage to the called program) are saved by the called 
program. 

T3ie minimum amount of storage needed for the save area of a program 
that is both calling and called is 19 words. Figure 19 shows the layout 
of the save area and the contents of each word, 

A called program that does not call another program need not estab- 
lish a save area. However, if registers 13 or 14 are used by the called 
program, that called program should save their contents and restore them 
before returning control to the calling program. 

Reserving a Parameter J^rea 

If a called program requires a parameter list, every program calling 
it must reserve an area of storage (parameter area) in which the parame- 
ter list used by the called prograir is located, Each entry in the pa- 
rameter area occupies four bytes at a f\allword boundary. If the parame- 
ter list is of variable length, the word preceding the first entry con- 
tains the length (in words) of the parameter list. Each entry contains 
the address of an argument to be passed to the called program. The Ciy^L 
macro instruction may be used to generate the parameter list as well as 
to link to the called program, 

Tliere are two types of linkage available to users of TSS: implicit 
linkage and explicit linkage. When an explicitly loaded module is no 
longer needed, it can be deleted explicitly. 
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SAREiA — >r 

(word 1) 

SjyiEA ♦ 4 
(word 2) 






|Lengt:hf in bytes, of the save area and any appen- 
jdages to it 

[Address of the calling program's save area. This 



SAREA + 8 
(word 3) 



SAREA -I- 12 — > 
(word 4,) 



SAREA ^ 16 — > 
(word 5) 



Address of the next save areaj that is, the save ar- 
ea of called program. This field is set by the 
called program 

Contents of register 11, containing the address to 
which return from the called program is made. This 
field is set by the called program in the calling 
program's save area 



SAREA + 20 — > 

(word 6> 

SAREA + 2<* — ^> 

(word 7> 

SAREA + 28 — > 

(word 8) 

SAREA + 32 — > 

(word 9> 



SAREA ♦ 68 
(word 18) 
SAREA ♦ 72 — > 
(word 19> 



field is set by the called program in its own save 
area 



H 



Contents of register 15, containing the address to 
which entry into the called program is made. This 
field is the called program in the calling program's 
save area 



^ 

Contents of register 



■i 



Contents of register 1 

contents of register 2 
I 



h 



Contents of register 3 



Eight words containing the contents of registers «* 
through 11 



h 
Contents of register 12 

I. , 1 

Address of the PSECT for the called program belong- 
ing to calling program. This field must be set by 
the calling program, by storing in it the R-con 
value of the called program 



Figure 19. Save area layout and word contents 



Implicit Linkage 

Program reference to a V- or R-type address constant (adcon) of an 
external symbol constitutes a request for iirplicit linkage. When an 
undefined external symbol is referred to in this manner, the loader is 
called to make available, in the user's virtual storage, those modules 
required to satisfy this external reference. This automatic action re- 
quires only specification of external symbols and adcon types as re- 
quired by the assembler. 

Explicit Linkage 

Within a given program there may be several references to different 
subprograms J however, for a given execution of that program, only one of 
those subprograms might be required. Since dependence on normal implic- 
it linkage would require, in the calling program, the presence of adcons 
for all such sutprograms, some unnecessary overhead would be experienced 
in preparing the unused adcons for linking. 
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It is also possible to develop, during prograro exectitiorit the exter- 
nal name of the module, entry point, or CSECT which is to be explicitly 
linked. In this case, it may not be possible to specify the modules to 
be linked during assembly. 

To allow for these situations, two explicit functions are provided 
that retrieve the desired subprogram at object time. The LOAD macro in- 
struction loads the desired program; the explicit CALL macro instruc- 
tion, in addition to loading the program, establishes the necessary 
linkage to it. 

Explicit Deletion 

The DELETE macro instruction makes virtual storage available by dis- 
pensing with a program that was explicitly loaded previously but is no 
longer available. Further, any other programs that are no longer re- 
quired as a result of the deletion of the specified program are also 
deleted. 
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APPENDIX Fs LmH CONTROL BLOCm FIELDS 



*Ihis appendix contains ascriptions of the contents of the fields of 
a data control block and the priority of the various sources for filling 
those fields, for those who desire to alter data control blocks or 
interrogate fields for the information contained therein, 

sources for Providing Data Set Attributes 

In general t a user writes a source program to create or process data* 
This data is considered to be a data set. In TSS, the system requires 
that certain attributes and identification information pertaining to 
data sets must be available to the system before a user can make use of 
the special programs and data management facilities comprising TSS. 

'Ehese attributes can be furnished to the system from two to six dif- 
ferent sources depending on whether the data set being processed is a 
new data set or a data set that has been previously defined to the sys- 
tem. The combined information provided by these sources must provide 
the system with all the information it requires to begin processing a 
particular data set. The six possible sources which provide the system 
with the attrilMtes of a data set are listed below in the order of their 
priority. Figure 20 indicates the DCB operands applicable to each 
access method and their valid alternate sources prior to opening that 
data control block. 

Source 1 - The User's Program 

The user may alter or fill data control block fields any time after 
the block has been created by a DCB macro instruction, h DCB macro in- 
struction with no operands merely reserves virtual storage for a data 
control block, with all its fields containing binary zero. The user has 
the opportunity to alter fields at OPEN time by specifying the address 
of a user routine that is to alter the DCB at open time? the routine is 
specified as the EXLST parameter of the DCB macro instruction or lower 
priority DDEF macro instruction or coiramand. Any user-coded data control 
block modification routine will find the DCBD macro instruction very 
convenient for referencing the fields of the control blcck. 

Source 2 - The DCB Macro Instruction 

Information may be supplied to the data control block by specifying 
operands in the DCB macro instruction. In this case, the DCB macro in- 
struction, in addition to creating a data control block, also fills the 
specified fields with the attributes indicated via the operands. 

Source 3 - The Catalog 

At the time a data set is cataloged certain attributes I data set or- 
ganization, data set disposition, device class, and data set affinity) 
are recorded in the catalog. When a user desires to re-open that data 
set for additional processing, information previously recorded in the 
catalog need not be specified again by another attribute source. If 
such recorded information is specified again by another attribute 
source, the previously recorded attribute information will take 
precedence. 
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I- — 



I- 

RECFM 

I- 

LRECL 



k 



i- 



DCB 

Operand 



J. 

PAD 



I- 

DEVD 



V 

BLKSI ZE 



I Applicable Access Method 

(■ 1 r T- T— r- 

! 



I Valid Alternate Sources | 



Specifies 

Symbolic name iden- 
tical to that used 
in ddnaire operand 
of DDEF cominand 
associated with 
data set 






Data set organiza- 
tion 



Record format in- 
formation 

Logical record 
1 ength 



4-- 



+- 



Address of user 
end- of- data routine 
for input data sets 

Optional service 
desired, write with j 
validity check (forj 
direct access de- 
vices only) 

Address of user's 
synchronous error 
exit routine (en- 
tered when an un- 
correctable error 
occurs in I/C op- 
eration) 



Key length 



Displacement of key 
from first byte of 
logical record 



-+ + 

Space to be left on 
each page of vir- 
tual index sequen- 
tial data set (to 
a How subsequent 
insertions) 

Types of iracrc in- 
structions used in 
processing data set 
(GET, PUT, READ, 
WRITE, etc.) 



Device on which 
data set resides 
plus, fcr soire de- 
vice types, device- 
dependent infor- 
mation (data cx>de, 
tape density, etc.) 






Maximum block 
length 

Number code indi- 
cating what system 
error recovery pro- 
cedures (if any) 

are to fce invoked 



Address of user ' 
exit list 



VSAM 

+. 

X 



— 4 

X 



— 4 

X 



4 -j._- 



CSAN 

-—4 

X 



4 

X 



4 4 ^ 4 4 



— 4- 



4 

X 



4 4 4 






VFAK 



__4 4 4 4 4 



^4 4 4 4 4 4 4. 



4 4 4 4 4 



--4— 



4 4 4_ 



4 



ESAM 



4 4 

X 



— 4 



4 4. 



4 4. 



4 

X 



QSAM 






ICREQ 



4 

X 



4™ 



User 's 
Pr eg rain 



4__, 



4 

X 



4 — 



X 



DEFINE 

DATA 

Coir ir and 









4 4 

X 



"4 



some 
device 
depen- 
dent 
infor- 
mation 






Data 

Set 

Label 






4 4, 



soire 
device 
depen- 
dent 
infor- 
mation 



4— 



— 4- 






Systero 

Service 
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Figure 20. DCB operands, their specifications, access irethods, and al- 
ternate sources (part 1 of 2) 
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Figure 20. DCB operands, their specifications, access methods, and al- 
ternate sources (part 2 of 2) 

Source 4 and 5 - The ppEf* M^:ro Instruction <4> Or Cominand C5> 

The DDEI macro instruction or command can supply the same information 
to all fields in the DCB as can be specified via the DCE macro instruc- 
tion, except for the EODAD, SYNiUD, and EXLST parameters. The DDEP macro 
instruction or command must be used for each data set to be processed 
because it is the only source of DSNAME, the data set name. The primary 
difference between the DDEF macro and command is the ability of the DDEF 
command to provide attribute information from the terminal at execution 
time rather than at assembly time. 

Source 6 - Data Set Labels or Data Set Control Blocks CDSCBs) 

At the time a data set is recorded on a storage device, a data set 
label or DSCB is created. The label or DSCB of an existing data set 
contains some data control block information. If fields in the data 
control block are still unspecified at open time, the information is 
taken from the data set label or DSCB and placed into the Data Control 
Block. 

Priority of Sources 

Many of the attributes of a data set that are required by the system 
can be furnished from more than one of the six possible sources. In 
such cases, each of the sources providing this information is assigned a 
priority and the system will use the information from the source with 
the highest priority. Waen two or more of the sources have correspond- 
ing entries, the attributes in the lower priority sources will be 
ignored. 

Ihis priority scheme provides great flexibility since information 
omitted in a higher priority source can be supplied by a lower priority 
source. Thus, if attribute parameters such as DSORG are not specified 
in the higher level DCE and DDEF macro instructions they may be supplied 
dynamically, at the terminal, by the lower priority DDEF command, or by 
the DSCB or tape label. 

If a field has been specified in the higher priority DCB or DDEF 
macro instructions at assembly time or by the user's program prior to 
OPEN, it will not be possible to modify that field dynamically from the 
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terminal Ce^g. , if there were a LRECL parariieter specification in the 
DDEF command at the terminal and the DCE also contained an LRECL speci- 
fication at assembly time, the LRECL specification of the DDEF coirmand 
would be ignored. In many cases, if a lower priority source provides 
the same attribute data as a higher priority source but the data pro- 
vided differs in each source, the system will issue diagnostics indicat- 
ing this. The system will either assume the higher priority source con- 
tains the valid data and continue processing based on that source or it 
will require the user to issue the proper matching attribute data in the 
lower priority source. Thus, if a user specifies a data set's organiza- 
tion CDSORG> in a DDEF command for a data set that is already cataloged, 
it must agree with the DSORG recorded in the catalog or diagnostics will 
be issued asking the user to reenter the correct data set organization 
parameter or to default to the system default value. In the latter 
case, if the user fails to provide the proper information and does not 
use the system default option the system will abend the user's task. 

The fields are presented in alphabetical order and are described in 
the following format: 



J. . ^ ^ ^ ^ — ^^ ^ ^ — ^ , — ^ 

I NAME (length) (name, name) I 

I specification of contents | 

i ^ . . ^ . J 

NAME 

is the keyword parameter nait^ if the field may be supplied by key-- 
word parameter in a DCB macro instruction. If the field is not 
supplied by keyword parameter, a meaningful name or phrase is 
giveni for example, retrieval address- 
length 

specifies the length of the field in bytes. 

name 

specifies the symbolic name or names which, when used in conjunc- 
tion with the DCBD macro instruction, will address the data control 
block field. 

An X in a bit position means that bit is not tested. 

BLKSIZE (2-byte field) (DCBBLKSI,DCBBLK> 

specifies a binary value for the maximum block length in bytes. 
The maximum value is 32,760. 

BUFL (2 --byte field) (DCEBUFL, DCBBUF) 

contains a binary number that represents the length, in bytes, of 
each buffer obtained for a buffer pool. The maximum is 32,7 60. 

BUFNO (1-byte field) (DCBEOfWO, DCEBDN) 

contains a binary number that represents the number of buffers as- 
signed to a data control block. The maximum is 255. 

BUFOFF (1 byte field) (DCBBOF, DCBCFT) 

specifies the length of the buffer offset field in bytes for ASCII 
tapes (may be specified only as a DCE subparameter of the DDEF com- 
mand) . An integer from to 99 may be specified. Acceptable buff- 
er offset values for various record formats and data set disposi- 
tions are: 
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i ^'"'^-^v.For ma t j 

[Dispcsition 

I NEW (OUTPUT) I 

I OLD (INPUT) I 



Undefined 




Fixed 1 


1 
Variable | 



0-99 




1 
- 99 1 


or 4 1 
0-99 j 



DDNAME C 8-byte field) CDCBDDNiyM^ DCBDDN) 

contains a name of up to eight character s, 

DEVD CI -byte field) (DCBDIVD, DCBDE¥) 



Code 

DA 

PT 

TA 

PR 

RD 

PC 

no device specified 



Bit Pattern 

11000100 

11100111 

11100011 

11010111 

11011001 

11010101 

11010110 



The additional keyword operands i^at are optionally \ised with DEVD= 
cause information to be inserted in dev^ ice- dependent parameters 1 and 2. 

Device Dependent Parameter 1 Cl-byte field) CDCBDDl) 

This byte is used to contain information from the KEYLEli operand that 
is subordinate to the DEVD= operand of the DCE macro instruction. 

KEYLEN (DCBKEYtE, DCBKEY) 

contains a birary number that represents the length, in bytes, 
of the key associated with a physical record* The maximum is 
255. 

Device Dependent Parameter 2 Cl-byte field) CDCBDD2) 

This byte is used to contain information from the TRTCH operand that 
is subordinate to the DEVD= operand of the DCB macro instruction. 

TRTCH CDCBTRT) 



Code 
C 

E 
T 
ET 



Bit Pattern 

00100011 

00111011 

00010011 

00101011 



Odd parity, no translation 00110011 
DSORG (2- byte field) (DCBDSORG, DCEDSC) 



Code 

PS 

PSU 

VI 

VS 

VIP 

VSP 

VP 



Bit Pattern 
OlOOOOOX 00000000 
01000001 00000000 



01110001 
01110010 
01110011 
01110100 
01110101 



00000000 
00000000 
00000000 
00000000 
00000000 



EODM) (8-byte field) (DCBEODVD, DCEEOV) for V-con 

(DCBIDDRD, DCBEOR) for R-con 
contains the address of the user^s EODAD routine. The first word 
contains the entry point address. The second word contains the 
address of the PSECT for the EODAD routine. If the EODAD routine 
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has no PSECT, 1:he second word contains the address of the CSECT 
containing the ECDM) routine. 

EROPT (1-byte field) (DCBEROPT, DCBERO) 



code 
ACC 

SKP 
i^BE 



Bit Pattern 
10000000 
01000000 
00100000 



Exceptional Condition Field 1 (l-byte field) (DCBEXl) 



Error Caused By 

GET 

POT 

SETL 

READ 

WRITE 

DELREC 



Bit Pattern 

00000000 

00000100 

00001000 

00001100 

00001111 

00010100 



Exceptional Condition Field 2 (l-byte field) (DCBEX2) 



Type of Error 

Keys equal - sequence error 

Key not found 

Keys out of sequence 

Keys do not coincide 

Keys coincide 

Invalid retrieval address 

Invalid record length 

Position past end of data set 

Position before beginning of data set 

Exceed maximum number of overflow pages 

Exceed maximum size of shared data set 



Bit Pattern 

00000100 

00001000 

00001100 

00001111 

00010100 

00011000 

00011100 

00011111 

00100100 

00101000 

00101100 



EXLST (4 -byte field) CDCBEXLST, DCBEXL) 

contains the address of a user-supplied exit list. The exit list 
must be in the same CSECT as the data control block, 

IMSK C4-byte field) CDCBIMSK,DCEIMK) 

contains the system error mask. The bit pattern is as specified 
under IMSK in the DCB macro instruction, 

LRECL (4-byte field) CDCBLRECL, DCELRE) 

specifies for format-F records the length in bytes of a logical 
record. For BSAM or QSAM the maximum value is 32,760 bytesj for 
VSMi, 1,048,576 bytes I for VISM4, 4,000 bytes. 

MACRF (2 -byte field) CDCBMACRF, DCBMAC) 



cede 

G 

GS 

P 

PS 

R 

RC 

RP 

i^ 

WC 

WP 



Bit Pattern 



01000000 
01000001 
00000000 
00000000 
00100000 
00100010 
00100100 
00000000 
00000000 
00000000 



00000000 
00000000 
01000000 
01000001 
00000000 
00000000 
00000000 
00100000 
00100010 
00100100 



Note: For GCSl, P[S] the bit pattern becomes the appropriate com- 
bination of the above bit patterns. 



270 



For RCC|P]t W[(P] ttie bit pattern becoroes the appropriate conibina- 
tion of the above bit patterns. 

NCP CI- byte field) CDCBNCP) 

contains a binary ninnber that represents the number of consecutive 
READ or WRITE macro instructions that are to be issued before a 
CHECK macro instruction is given. The maximum is 99. 

OPTCD (1-byte field) (DCBCPTCD^ DCECPT) 



A - ASCII tape request 
W - write validity check 
Default: no service is performed 



Bit Pattern 
XXIOOOOO 
10000000 
00000000 



OPTIONS (l--byte field) CDCBOPI) 

contains the bit patterns specified by option parameters in the 
OPEN and CLOSE macro instructions. 



OPEN OPTl 


OPEN 0PT2 


CLOSE OPT 


Bit Pattern 


INPUT 






xxooooxx 


OUTPUT 






XXllllXX 


INOUT 






XXOOllXX 


OUTIN 






XXOlllXX 


RDBACK 






XXOOOIXX 


UPDAT 






XXOIOOXX 




REREAD 




OIXXXXXX 




LEAVE 




IIXXXXXX 






REREAD 


XXXXXXOl 






LEAVE 


XXXXXXll 



PAD (1-byte field) CDCBPAD) 

contains a binary number that repres^its the space, as percentage, 
left available within the pages of a VISAM data set, providing for 
insertions within the pages of a VISAM data set. The maximum is 50 
C50 percent). 

RECFM (1-byte field) (DCBRECFM,DCBREC) 



code 

u - 

V - 
VE - 

D - 
DB - 

F - 

FB - 

FS - 

FBS - 

A - 

M - 



(ASCII tapes) 

(ASCII tapes) blocked 



undefined 

variable 

variable blocked 

variable 

variable 

fixed 

fixed blocked 

fixed standard 

fixed blocked standard 

Extended ANSI FORTRAN control characters 

machine code control characters 

no control characters 

KEYLEN specified in data control block 



Bit Pattern 

11X0 OXXX 

OIXXOXXX 

OIXIOXXX 

IXIXXXXX 

IXIIXXXX 

lOXXXXXX 

lOXlXXXX 

lOXXlXXX 

lOXllXXX 

XXXXXIOX 

XXXXXOIX 

xxxxxoox 

XXXXXXXl 



EXAMPLE : If this byte contains 10 010100, the record format is fixed 
length, blocked records with an ANSI FORTRAN control character. 



Retrieval Address for Virtual Access Method (4-byte field) (DCBLPA) 

This field contains a retrieval address that is used for recording 
and repositioning to specified records of a data set. 
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Retrieval Mdress for QSMl (6-byte field) CDCBLPDQ) 

This field contains a retrieval address that is used for recording 
and repositioning to specified records of a data set, 

RKP C2-byte field) CDCBRKP) 

contains a binary niamber that represents the displacement of the 
key field of a record from the first byte of the record, 

SYNAD (8-byte field) (DCBSYNVD, DCESYV) for V-con 

(DCBSYNRD^ DCBSYR) for R-con 
contains the address of the user's SYNM) routine. The first four 
bytes contain the entry point address- The second four bytes con- 
tain the address of the PSECT for the SYNAD routine. If the SYNAD 
routine has no PSECT, the second word contains the address of the 
CSECT containii^ the routine. 
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I^PPENDIX Gs DETAILED DESCRIPTION OF DDEF MACRO ItiSTBUCTIOli 



This appendix describes how the DDEF macro instruction is used to 
define a private data set or a nonstandard public data set. For infor- 
mation on the definition of standard data sets, refer to the description 
of the DDEF macro instruction in the main body of this manual. (Stand- 
ard data sets have virtual sequential organization, are on direct access 
public storage, and are arranged in units of pages.) Figure 21 lists 
required and optional operand fields of the DDEF macro instruction. The 
format of the DDEF macro instruction is as followss 

Standard form: 

[Name | Operation {operand | 

I [symbol] I DDEF ({address of operand string] 'operand string •> | 



L-formt 

J- , — ^ ^ , ^ — ^ ^ ^ ^ 

I Name | Operation | Operand | 

I symbol | EDEF \ • operand string • ,MF=L | 

E-f orm: 

J— ^ ™^i . ^ ^ , ^ 

I Name | Operation Operand j 

I ^^+ ^ .„^ ^. 4 

I Csyroboll | DDEF j MF=(E,list> | 

address of operand string 

specifies the address of the first operand of the operand string 
(see "Operand Strings" in Part II, Section 1). 

Specified as s Register notation (2 through 12), or a relocatable 
expression. Note that the operand string can also be specified as 
a character string enclosed in apostrophes, as shown. 

operand string 

specifies the operands of the DDEF macro instruction; the operands 
are shown in Figure 21. 

Specified as ; A continuous character string enclosed in apos- 
trophes. The way to specify each operand is described following 
Figure 21. 
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I 



ata definition nainel Cdata set organization] ,DSNAME= (name ( 
CSCUT S l*name! 



,DCB=([*data set name] [,DSORG=organi2ation] C|,MACRF=iracrc form] 

CtBUFL=buffer length] [,DEVD=device] [,BUFWC=n\iirber of buffers] 
[pBFTEK=buff er technique] C ,NCP=check n'ninber] 
[,RECfM=record f ormat] [ ^OPTCB=CW| A} ] C,LRECL=record length] 
[,BLKSISE=inaxiimiin block length] [ ,KEYLEN=key length] 
C,PRTSP=spacing] C,STACK=stacker bin] [,DEN=density tape) 
[yMOE^=niode of operation] I ^TRTCH=re cording technique] 
CfEROFr=error option] CyPAD=av ail ahl e space] 
t,RKP=key field displacement] [ ,IM£K= err or procedures] 
£,BUEOFF=buffer offset field li qth]) 



[,UNIT= 




direct access type] 
tape type] 
ce address 



'V 



LSPACE=c4cYL i ^primary allocation C , secondary allocation] I, HOLD])] 

(record length^ 



, fpUBLIC 

^ ^raLUME= (4 PRI VA-HE 



(volume sequence number j Ivolume serial number 



[, J PRIVATE 



1 



..3)3 



£,I,ABEIi= Cf ile sequence number] ( ^latel type] C, RE TPD=re tent ion period])! 
[^DISP=data set status! ( ,CPTI0N={JCBLIB1C0NC}1 
[,RET=(tP|!r)lC|L! [U|R])! 
[,PROTECT=CY|N>! 
Figure 21* Operands for DDEF macro instruction 



data definition name 

specifies the symbolic name associated with this data set defini^ 
tion. It provides the link between the data control block in the 

user's program and the data set definition. 

Specified as s One tc eight alphameric characters, the first of 
which roust be alphabetic. The user is not allowed to use a name 
that begins with SYS| the system-reserved names are prefix,ed with 
these characters • 

PCSOUT 

specifies that the program checkout subsystem is being used and a 
data set is being defined for dumps. One PCSCUT-~type DDEF command 
or macro instjcucticn is required when the DUMP command is to be 
employed, 

Specified as ; PCSCOT 

data set organization 

specifies a two-character code that indicates the organization of 
the data set« It must be specified for non-¥AM data sets but is 
optional for VAM data sets. 

Specified as s 

PS - QSAM or BSAM (physical sequential access methods) 
VI - VISAM {virtual index sequential access irethcd) 
VS - VSAM (virtual sequential access method) 
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VF ~ VPAM (virtual partitioned access irethod) 
RX - lOREQ (I/O request) 

Default : The data set is assigned the type of organization speci- 
fied at systeir. generation. 

DSNAME= 

specifies the name of the data set. 

Specified as ; Name or ♦Name^ where: 

name 

specifies the name of the data set. This is the name under which 
the data set may be cataloged or referred to during the task, h 
relative generation number and/or a partitioned data set member 
name may be included with the name. 

Specified as s The fully qualified name of a partitioned or nonpar- 
titioned data set, a member of a partitioned data set, or a parti- 
tioned or nonpartitioned generation of a generation data group (i- 
dentified by absolute generation name or relative generation 
number ) . 

For ASCII tape input, the data set name may include any ASCII 'a' 
character (an alphameric or graphic character), except the under- 
score and alternate graphics character. The format is DSNAME= 
•bnaroe", where the leading blank indicates I^SCII characters, or 
DSNAMl=name if only alphameric characters are used. 

♦name 

specifies the name, here prefixed by an asterisk (♦)t ot a data set 
created under IBM OS or OS/VS. Subsequent references to this data 
set name do not include the asterisk prefix. 

Specified as ; same as for the DSNAMl=name form, with a maximum of 
44 characters, excluding the asterisk. 

DCB= 

specifies the data control block information, as follows: 

data definition name 

specifies the data definition name of a previously issued BDIF com- 
mand or macro instruction. The previous name is prefixed by an 
asterisk (♦) to indicate that the data control block field of that 
DDEF is to be duplicated for the current CDEI macro instruction or 
command. Any new suboperands given in the remainder of the field 
take precedence over the corresponding suboperands of the previous 
DDEF command or macro instruction. 

Specified as ; One to eight alphameric characters, the first of 
which must be alphabetic, preceded by an asterisk. 

DCB suboperands 

detailed descriptions of the data control block suboperands are 
given in the discussion of the DCB macro instruction for each 
access method, and in Appendix F« Those suboperands that cannot 
also be specified as operands of the DCB macro instruction are de- 
scribed below. The MODE and STACK suboperands are described under 
"DCB CMS AM) Options* in System Programmer's Guide . 

BUF0FF= (BSAM) 

specifies for ASCII tapes the length of the buffer offset field in 
bytes. 
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Specified as ; An integer to 99. See Appendix F for a table of 

acceptable buffer offset values for various record formats and data 
set dispositions. 

D1N= CIOREQ) 

specifies a value for the tape recording density, in bits per inchi 



r- 


"■ '^^ "■ -"■ —^ -^ ■-» ■"- ""■ *-"■ 


"T * — r- 


1 


1 


DEN Value 


1 7 -Track | 
I 200 1 


9 -Track | 
^ ^ 

error | 







1 


1 556 1 


error \ 




2 


1 800 1 


800 1 




3 


1 error j 


1600 1 




4 


1 error | 


6250 1 


L. 




-X -.-A« 


^ , 1 



Note ; If the data set is or will be on tape, the DEN subopexand of 
the DCB operand is required to specify the density of the data set. 
If the data set exists, or if another data set exists on the tape, 
the density of the existing data set is used, and the DEN sub- 
operand is ignored. If the density of a new data set on an eropty 
tape is not specified, the tape density established at systeir 
generation is used, in which case the BUFOFF suboperand is not 
required. 

Caution : The DEN and BUFOFF suboperands may be specified as DCB 
suboperands only; they iciay not be specified in the DCB macro 
instruction. 



UNIT= 



specifies the type of device needed for the data set. Allowable 
devices are specified at system generation and, therefore, may be 
changed. Direct access devices may be specified for either public 

or private volumes. Tape may be specified for private volumes 
only. 

Specified as ; 

DA - specifies that a direct access device is required for the 
data set* 

direct access type - specifies the type of direct access device. 

Specified as t A four- digit number. 

Default : The system selects the type cf direct access device, as 
specified at system generation* 

TA - specifies that a tape unit is required for the data set. 

tape type - specifies the type of tape required. 

Specified as ; 

7 - any 7-track tape unit 

7DC - 7-track tape unit with Data Converter installed 

9D2 - *I""track tape unit with 800 bpi capability 

9D3 - 9-track tape unit with 1600 bpi capability 

9Dil - 9-track tape unit with 6250 bpi capability 

Default; The system selects the type of tape specified at system 
generation, 

device address 

specifies the symbolic device address of a nonstandard device.. 
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SPACE= 

specifies the direct access storage allocation for the data set* 
If the entire space field is defaulted , the direct access storage 
allocation specified at systeir generation is assigned. 

Specified as ; 

TRK - specifies that the space requirements are expressed as a num* 
ber of tracks. 

CYL - specifies that the space requireroents are expressed as a nxxm- 
ber of cylinders. 

record length 

specifies the average record lengthy in bytes, of the physical 
records . 

Specified as : A decimal number not exceeding 32,767. 

Defaults If the data set organization is SAM, the unit of allo- 
cation is assumed to be a cylinder. If the data set organization 
is Vim, the unit of allocation is assumed to be a page (4096 
bytes) . 

primary allocation 

specifies the number of units to be allocated initially to the 
data set. 

Specified as ; JV 1- to 8-digit decimal number? roax=0006553 5. 

Defaults The primary space allocation assigned at system genera- 
tion is assigned. 

secondary allocation 

specifies the number of units to be allocated each time the space 
allocated to the data set has been exhausted and more data is to 
be written. 

Specified as ; A 1- to 8-digit decimal number? max=0000025 6. 

Defaults The secondary space a 1 location specified at system 
generation is assigned. 

Note: If more than 256 units are requested, only 256 will be 
allocated. 

HOLD 

specifies that the unused storage assigned tc this data set is 
not to be released when the data set is closed. 

Specified as s HOLD 

Defaults Unused storage is released. 

VOLIME- 

specifies the volumes on which the data set resides. This field 
must always be used when creating a new data set residing on a pri- 
vate volume or when referring to an existing uncataloged data set 
residing on a private volume. This field also must be used when 
expanding an existing private cataloged or uncataloged data set. 
When expanding an existing private cataloged data set, only the new 
volumes to be added to the data set (options of PRIVATE or volume 
serial number) need be referred to. 
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This field is not required for data sets on public volumes. Howev- 
er^ this field may optionally te specified f cr new data sets on 
public volumes providing only existing public volume serial numbers 
are specified. Initial space allocation will then te limited to 
the specified volumes- 

Specified as ; 

PUBLIC - the data set is to be placed on public storage volumes. 

PRI¥I^T1 - volumes are to be allocated from the system pool Ci-e., 
the scratch tapes cr disks available to the system operator) • Once 
assigned, the volume remains the user's, exclusively, until he 
notifies the system operator that it can be returned to the pool. 
The user must use this option to request initial or additional 
scratch volumes for data sets on private vclumes. 

Specified as ; A one-to-four digit number. 

volume sequence number - the sequence number of the first volume of 
the data set to be read or written. It is meaningful only if the 
data set has SMi organization, is cataloged, and its earlier 
volumes are not to be processed. 

Note : If the volume sequence number is specified, the data set is 
cataloged and the serial numbers are retrieved from the catalog. 
If PRIVATE is specified, the system assigns a volume serial number. 
If the volume sequence number or PRIVATE options are used to extend 
the voltame list for an existing cataloged data set, the volume 
serial numbers in the catalog are used for the existing portion of 
the data set, regardless of whether they are also specified in the 
current DDEF. 

volume serial number 

specifies the volume serial numbers identifying the volumes on 
which the data set resides. The volume serial number is required 
for old uncataloged data sets that reside on private volimnesj the 
user must use this option tc specify initial cr additional volume 
serial numbers for data sets on private volumes. It is optional 
for new data sets on public volumes. For ASCII input data sets, 
any ASCII 'a* character (alphameric or graphic), except for the 
underscore and alternate graphic character, may be used. 

Specified as ; One to six alphameric characters; characters other 
than alphamerics may also be used, in which case the volxame seri- 
al number must be enclosed in apostrophes. Example: 

WLUME=(,«A1*%», 123456, •#,'•123') 

Default; If the volume sequence number was specified, the data 

set is cataloged and the serial numbers are retrieved from the 

catalog. If PRIVATE was specified, the system assigns a volume 
serial number. 



IJ^BEL= 



specifies the labeling conventions. 

Specified as ; See below. 

Default ; If the entire label field is defaulted, the labeling 
conventions specified at system generation are assigned. Howev- 
er, if the data set is cataloged, label information is retrieved 
from the catalog. 
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file sequence nuirfcer 

specifies the file sequence number of a data set when multiple 
data sets are on one tape volume. 

Specified as ; A one- or two-digit decimal number. 

Default: The data set is assumed to be the first Cor only) one 
on the tape volumie. 

label type 

specifies either the type of labeling desired or the absence of 
labels - 

Specified as : 

NL - no labels (ASCII or EBCDIC tapes only) 

SL - standard labels 

SUL - stamdard labels and user labels 

AL - standard ASCII labels 

AUL - standard ASCII and user labels 

Default ; The system assumes the label type specified at system 
generation. 

RETPD 

specifies the retention period of the data set. This operand ap- 
plies to data sets on direct access volumes or on labeled tapes. 

Specified as : A four-digit decimal number that indicates the 
time period, in days, that the data set is tc be retained after 
its creation. 

Defaults The retention period is assximed to be zero days, thus 
allowing immediate rewriting. 

DISP= 

specifies the status of the data set. 

Specified as s 

NEW - for a new data set. 

OLD - for an old data set. 

MOD - the data set exists but is being added to. MOD causes logic- 
al positioning after the last record of the data set. It ap- 
plies only to SAM data sets on private volumes. 

Default s OLD - for old cataloged data sets. 

NEW - for a new data set or for an old uncataloged pri- 
vate data set. 

If DISP is defaulted in a DDEF for an existing cataloged public 
data set, the system assumes a value of OLD. If DISP is defaulted 
for any data set that does not yet exist, the systoci assumes a 
default value of NEW. It should be noted that, for existing uncat- 
aloged private data sets, the DISP value must be explicitly speci- 
fied as OLD. If the user tries to default such a data set, a DISP 
value of NEW is assumed and causes a system error. 

OPTION= 

specifies that either a job library is being defined or a data set 
is being added to the concatenated data set named in the data 
definition name operand. 
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Specified as s 

JCELIE ~ the data set is to be used as a job library. The data set 
name specified in the DSNIIME field will be entered into the prograro 
library list. 

CONC - this data set is to be concatenated with one or more data 
sets whose data definitions have the same data definition naire. 
Only input data sets that are not job libraries can be concate- 
nated. The order of concatenated data sets is the same as the 
order in which they are defined. 

RET= CVJVM only) 

specifies codes for the storage type, deletion option, and owner 
access that will be used in processing the data set. 

Specified as ; C [P|THC| 1] [U| Bl ) , where the codes have the 
following meanings: 

Codes Meanings 
P Permanent storage 
T Temporary storage 

C Delete at CLOSE 
L Delete at LOGOFF 

U Read-write access 
R Read only access 

Default ; P; If a deletion option is not specified for a temporary- 
data set CT) , L is assumed; U. 

PROTECT= 

specifies whether the tape being mounted is tc have a file-protect 
ring in. If Y is specified, the tape is to be mounted without a 
file-protect ring, unless the disposition of the data set being de- 
fined requires a ring, in which case DDEF processing is terminated? 
a tape already mounted with a file-protect ring in it will have to 
be remounted in order to have the ring removed. If N is specified, 
the tape is to be mounted with the ring in, regardless of the dis- 
position of the data set being defined; if the tape is already 
mounted without a ring, it will have to be remounted in order to 
have a ring put in it. 

Specified as ; 

If - no ring, file is protected 

N - ring in, no protection. 

System default ; N for DISP=NEW and DISP=MQD. For DISP=OLD the 
default is left tc the option of the installation. If this operand 
is omitted for DISP=OLD, there is no verification of the file pro- 
tection status. 

The DDEF macro instruction or command that defines any cataloged data 
set is brief and simple'. The only required operand fields are the data 
definition and data set names. Other operand fields are unnecessary 
since the organization of the data set is described in its catalog 
entry • 

DDEF macro instructions or commands that define uncataloged data sets 
may be divided into two groups; those defining new data sets (i.e., 
data sets that will be generated during the run but do not exist as yet) 
and those defining old (already existing) data sets. These old uncat- 
aloged data sets can exist only on private volumes. 
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To define a new data set that will be written on a public volmre, the 
user may use the data definition name, data set name, SPACE, data set 
organization, and LABEL operand fields. Exactly which fields he uses 
other than the data definition and data set names, which are required, 
depends on the character of his particular data set. 

*ro define a new data set that will be written on a private volume, 
the user must give the data definition name, data set name, UNIT, and 
VOLUME operands* If desired, he may also fiirnish the data set organiza- 
tion, SPACE, LABEL, and DISP fields. 

The user defines an old, iincataloged data set just as it stands on 
his private volume. To do so, he must use the data definition name, 
data set name, VOLUME, UNIT, and DISP fields. He may also employ the 
data set organization and LABEL fields. 

Note s The DCB is required to specify tape density for any uncatalogued 
data set on tape. However, it may be defaulted if the tape density 
matches that established at system generation. 

The DDEF macro instruction or command also has several special uses: 

1. To define a job library. Operand fields are as follows: 

data definition name,VP,DSNAME=data set naice, 
DISP= (OLD) ,OPTION=JOBLIB 

No other fields are reguired- 

2. To define a data set for dumps. Operand fields ares 
PCSOUT,VI,DSNAME=data set name 

Other fields are as needed. 

3. To complete the data control block of a data set at execution time. 
The deb field is included in this case? other operand fields are as 
needed for the particular data set. 

4. To concatenate data sets (i.e., to define them, for input purposes 
only, so that several data sets can be read as if they formed a 
single data set. The OPTION=CONC field is included? other fields 
are as needed for each data set. The OPTICN=CONC field must be 
given in the DDEF for each data set except the first-defined member 
of the concatenation. The remaining data sets in the concatenation 
must each have the same ddname as the first-defined data set. 

The DDEF macro instruction or command causes a system entry to be estab- 
lished for the DDEF information so that allocation routines and access 
methods can refer to it. The link between this information and the pro- 
blem program's reference to the data set (i.e., the data control block) 
is the data definition name. The entry containing the DDEF information 
is maintained until the user logs off or until, through the RELEASE 
macro instruction or command, the data set is released. 

The DDEF macro instruction or command also results in a request, when 
necessary, for device allocation and volume mounting if the defined data 
set is private and resides on a demountable volume such as a reel of 
tape or a disk pack. 
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Typical Use of DDEF Operand Fields 
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Data Set Organization Requirements 
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Data Set Organization Requirements (continued) 
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Programming Notes ; The DDEF macro instruction or command may be used in 
conversational and nonconversational tasks. 

The user's relies to diagnostic messages issued for his DDEF macro 
instruction or command should be guided by; 

1. If the diagnostic message calls for reentering an element within a 
given operand field, only that element should be reentered. Pre- 
ceding and/or following delimiters are unnecessary. Default is 
acceptable. 

2. If the diagnostic message calls for reentering a complex operand 
field, the whole field should be reentered, including the keyword 
and equal sign. Default is acceptable. 

3. If the diagnostic message calls for reentering an operand field 

that consists of only one element in addition to the keyword, the 
reply may be either the element alone or the keyword, equal sign^ 
and element. 

4. If the diagnostic message calls attention to an inconsistency and 
asks the user to enter one of two or three specified operands, tbe 
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reply must be a complete operand field, A default is acceptable 
only if so stated in the message- 

Ibe user is informed if the BDEF macro instruction or command cannot 
be completed- This action can occur for one of these reasons: 

1. Invalid punctuation in the operand string. 

2. User's volumes cannot be mounted. 

3. Sufficient space cannot be allocated. 

4. More than three logical inconsistencies were detected in the BDEF 
macro instruction or command. 

Whenever possible, correction and completion of the command will be 
attempted. But if diagnostic messages indicate that a parameter was 
misunderstood because of a punctuation error in the operand string, the 
user should interrupt the operation (by pressing the ATTENTION key) and 
reenter the corrected command. In confirmation mode, he may prefer to 
wait for prompting. 

The user must never reenter a parameter or part of a parameter that 
was not requested. 

If a keyword is missing or invalid, the pertinent elonents following 
it must be reentered after the corrected keyword and equal sign are 
typed . 

If a parameter occurs twice in the operand string, the second occur- 
rence is preferred. All elements belonging in the earlier occurrence 
are erased. 

DDEF prompting messages are issued according to the operand informa- 
tion already si:^plied. Unnecessary prompting is kept to a minimum. 

If the user's program is being executed in conversational mode and an 
undefined data definition name is referred to, prompting messages for 
DDEF operands will be issued to the user, regardless of confirmation 
mode. 

Return Data ; At completion of execution of the DDEF macro instruction 
or command, a code is loaded into the low-order byte of register 15 and 
register 1 contains the identification of the diagnostic message that 
explains the error (for nonzero codes) . 

Code Significance 

00 Successful completion. 

04 Undefined data set name (for old data set). 

08 Data set name not unique (for new data set). 

OC Attention interruption. 

10 Data set organization in DDEF parameter list is not 

the same as in catalog. 

14 Nonexistent generation name. 

18 Data set name not fully qualified. 

IC Volume could not be mounted. 

20 Space not available. 

40 Data definition name not unique. 

80 Any error condition not listed above. 
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APPEHDIX I: 



INTEBBUPTION HAHDLIHG FACILITIES 



Time Sharing System provides macro instructions that permit the user 
to control task interruptions (Figure 23) - 
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Figure 23. TSS interruption handlir.g facilities 



IHIERRUPTIO:! MAHDLI^G 

TSS espioys interruptions to facilitate the dispatching of 5 y stem 
service routines an2 interruption error-handling routines. Examples of 
service routines provided with the system are Paqe Handling, I/O serv- 
ices, and Main/Auxiliary storage allocation- System program error 
interruption-handlinq routines are dispatchei in response to STSI^ at- 
tention interruptions, task timer interrootions, external, I/O, nachine 
check, program, or SVC-gene rated interruptions. These intarruotion- 
servicmg routines attempt to correct any hardware or software error 
situations that occur darina the execution of privileged systeii 
programs. 
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Figure 22. Literals generaxea cy nracro instructions Cpart 4 of 4) 
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APPENDIX I: INTERRUPTION HMTDLING FACILITIES 



Time Sharing System provides macro instructions that permit the user 
to control task interruptions (Figure 23). 
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Figure 23. TSS interruption handling facilities 
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Normally, except for attention interruptions at the SYSIN terminal, 
interruptions occurring during non-privileged problem programs are not 
serviced by the system in the same manner. In such cases, an interrup- 
tion causes an appropriate error message to be written from the system 
message file onto the task's SYSOUT device. If the task is conversa- 
tional, the user is prompted for corrective action. If the task is non- 
conversational, the task is abnormally terminated. 

User Interruption Facilities 

To give the user more flexibility in the handling of interruptions 
occurring during the execution of his problem programs, TSS provides a 
user with facilities for supplying his own interruption-servicing rou- 
tines. Examples of service routines that may be supplied by the user 
includes program interruption- handling routines, routines for creating 
and handling unused SVC codes, routines for handling task timer inter- 
ruptions, and for handling special task I/O interruptions. The basic 
interruption-handling logic used by the system and the interruption- 
handling macro facilities provided to a user by TSS are summarized 
below. 



BASIC INTERRUPTION SERVICING LOGIC 

A system interrupt table is used to establish a gueueing mechanism 
for any interruptions occurring on the various devices in the system. 
The Interrupt Table (see Figure *♦> holds information concerning device 
types, interruption-servicing routines, and interruptions to be process- 
ed. There are three main types of entries in the tablet Device Entries 
(DE>, Request Entries CRE), and Queue Entries CQE) • A device entry 
exists for each source that can signal interruptions to the system. 
Thus, they exist for each physical I/O device attached to the system as 
well as for the logical sources causing program interruptions, SVC, ex- 
ternal, and timer interruptions. 

Request Entries are attached to the device entries. There must be an 
RE for every service routine which may be dispatched to handle interrup- 
tions. A QE generally represents a particular interruption, and all 
interruptions that are to be serviced by the same routine have their 
Queue Entries chained to the RE that is associated with the routine that 
is to service that type of interrupt. 

The Device Entry is constructed by one of two methods j the SIR macro 
instruction builds it into the interrupt table or it is predefined at 
SYSGEN. A set of Request Entries is attached to appropriate device 
entries in the interrupt table at system assembly or dynamically during 
task initiation to provide for the dispatching cf system service rou- 
tines and interruption error- handling routines supplied by the system. 
Queue Entries are entered in the Interrupt Table, by the system, and at- 
tached to a particular Request Entry, when an interruption occurs. 

When an interiruption routine is dispatched, linkage between the sys- 
tem q,ueueing mechanism and the various system or user -provided interrup- 
tion servicing routines is generally established by two other areas 5 
the Interrupt Control Elock and a Communication Area. A brief descrip- 
tion of the contents of Device Entries, Request Entries, Queue Entries, 
interrupt control blocks and the Communication Area follows. 

Device Entries - the device entry contains a device type code, a highest 
priority. Request Entry Code, a highest priority active request entry 
code. Predefined device entries exist for four of the six interrup- 
tion types (program, SVC, external, and tiirer) . The asynchronous and 
synchronous I/O interruption device entries are built by SIR for each 
device allocable in the system. 
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Request Entries - the request entry contains an activity indicator, an 
interruption servicing priority code, a pointer to a description of 
the service routine (contained in the ICE) , and a pointer to its 
queue entries (if any exist). 

Queue Entries - contain the necessary interruption information frcm the 
VPSW and the sense and status information from the ISA required by 
the system at dispatch time. Seme of the information in the QE is 
moved to a user defined Communication Area (com) at dispatch time so 
he may analyze the conditions and status at the time of the inter- 
rupt. The QE represents the occurrence of an interruption of the 
type specified in the RE to which the QE is attached (chained) . 

Interrupt Control Blocks ~ specifies what type of interruptions are to 
be processed, by a particular interruption-servicing routine, under 
what conditions the servicing routine is to be entered, and the entry 
point address of the inter jrupti on routine. It also points to a com- 
munication area in the user problem program in which information 
identifying the type and status of an interruption is placed by the 
system when an interruption occurs. 

Communication Area - in addition to its primary purpose of holding in- 
terruption information for analysis by an interruption servicing rou- 
tine, it allows information to be passed between an interruption rou- 
tine and the interrupted program, (in which the comrotanication area 
must reside). Thus, a field in the communication area may be used as 
an event control block where completion of interruption processing 
can be posted. The system places QE information in the communication 
area when an INTINQ macro instruction with the CLEAR mode is speci- 
fied, and when a QE is dispatched to its interruption servicing 
routine. 

The relation of these areas is shown in Figiire 2^. 

User Establishment of Interruption Handling Routines 

^en a user desires to service particular interruptions occurring in 
a problem program, he must create the entries and control areas required 
by the system for servicing that type of interruption. Thus, as shown 
in "Basic Interruption Handling Logic," the user must create a Request 
Entry, Interrupt Control Block, and Communication Area. Device entries 
not entered at SYSGEN are entered via user issuance of a SIR macro in- 
struction. A Queue Entry will be created by the system when an inter- 
ruption occurs and does not have to be created by the user. 

The TSS macro facilities provide a user with an easy method of accom- 
plishing this. During problem program execution a user can create his 
own servicing routines for six kinds of interruptions. These six inter- 
ruption types and the macro instructions used to create the ICB for each 
type is indicated below. 

Macro Instruction 

Interruption Type for Creating ICB 

Program interruption handling routines SPEC 

Routines for handling SVC codes not recognized SSEC 

by the system 

I/O interruption handling routines SIEC 

Task timer interruption handling routines STEC 

Asynchronous interruptions SAEC 

External interruptions SEEC 

The Communication area must be coded by the user in the format illus- 
trated in the descriptions of the above macro instructions. 
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Figure 24. Interruption handling logic 
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Once an ICB has been created 1^^ a problem program and a commtanication 
area is established, a user can issue the SIR iracro instruction to 
attach a Device Entry (if one does not already exist) and a Request 
Entry (RE) to the interrupt table, and establish a priority for the han- 
dling of the interruption type. 

Ihe user should avoid issuing a FREEMAIN macro instruction on an ICB 
that has a currently active interruption routine, 

After the user has established the RE, ICB, and communication area 
for a particular type of inter irupt ion, and that type of interruption 
occurs, the interrupt table is searched, the user-created RE is located, 
and the system attaches a QE to the RE, (Note the exception to this un- 
der "SYSIN Attention Interruption Handling,*) The System's task inter- 
ruption queueing mechanism then causes the subsequent dispatching to ap- 
propriate user-coded interruption handling routines by priority. 

Writing Interruption Servicing Routines 

When an interruption occurs in a nonprivileged routine, an asynch- 
ronous exit is taken from the interrupted routine and control is passed 
to the entry point of the user's interruption routine (which roust be 
aligned on a fullword boundary). Information identifying the type of 
interruption that occurs is made available in a communication area in 
the interrupted program. When the interruption routine is entered, 
register 1 contains the address of a two-word parameter list. The first 
word of the parameter list contains the address of a communication area, 
and the second word contains the address of a data control block (Figure 
25) . 
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♦See description of SPEC,SAEC,SIEC,SSEC,SE1C, cr STEC macro instruc- 
tions for format. 



Figure 25, Information available upon entry to an interruption routine 

Using this information, the interruption routine can perform any cal- 
culations necessary, issue input/output macro instructions, and do what 
is necessary to respond to the interruptions, 

An interruption servicing routine might want to take one of several 
actions, depending on the occurrence and status of other interruption 
events. The user has been given the capability of inquiring as to the 
status of other user-specified interruption routines with respect to the 
existence of outstanding interruption events. The information pertain- 



294 



ing to a particular interruption and held in its Queue Entry may be 
inspected by the interruption servicing routine through use of the 
Interrupt Inquiry CINTINQ) macro instruction in an interruption process- 
ing routine. INTINQ can be used tc determine whether specified inter- 
ruption events have occurred. It uses a user-specified ICB to determine 
if any QEs exist that are associated with the interruption- servicing 
routine described by that ICB. If a QE exists it indicates that an in- 
terruption of that type has occurred. The subsequent action of a user 
interruption-servicing routine in which INTINQ was issued is determined 
by the occurrence or nonoccurrence of the specified interruption and the 
mode set by the INTINQ macro instruction. These modes and the actions 
taken by the interruption-servicing routine are summarized below. 
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Required Interrupt 
QE Information 

Available 
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CLEAR! 
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Not Available] 



Relinquish control, thereby passing 
control to one of the user's lower- 
priority interruption servicing rou- 
tines, or return control the user*s 
task at the point of interruption. 
The occurrence of the expected inter- 
ruption returns control to the inter- 
ruption routine and resumes execution 
at the instruction following INTINQ. 
~+ 



Action 



Continue execution with the next 
sequential instruction in the inter- 
ruption servicing routine 



H 



Continue execution with the next 
sequential instruction in the inter- 
ruption servicing routine. 

Enter the wait state, ^hen and if the 



expected interruption occurs, control 
is returned to the interriiption serv- 
icing routine and execution resumes at 
the next sequential instruction fol- 
lowing INTINQ. Any higher priority 
interruptions occurring while this 
routine is in the wait state will be 
processed. 

+ 



Branch to specified branch address. 



Continue execution with next sequen- 
tial instruction. 

Moves the information from the QE to 
the communication area, deletes queued 
interruptions , and processing contin- 
ues with next sequential instruction 
following INTINQ. 



L i. 






Processing continues with next sequen- 
tial instruction. 
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Disabling Interroptions During Exectation of Interrtap-tion Servicing 
Rou-tines 

In order to ensure 1:hat an interruption servicing routine can or can- 
not be interrupted by subsequent interruptions ^ two macro instructions, 
SAI and RAl, are provided to the user by TSS. Issuance of the SAI macro 
instruction in an interruption- servicing routine inhibits stabsequent 
interruptions from taking place while the interruption-handling routine 
is being executed. No interruptions will be lost, however, because they 
are queued up. If interruptions are not disabled by SAI, interruptions 
of higher priority can interrupt a lower priority interruption-servicing 
routine. If a user desires, he may issue a RAl iracrc instruction that 
will allow all subsequent interruptions to interrupt his servicing rou- 
tine regardless of their priorities. 

SYSIN Attention Interruption Servicing 

Normally, user interruption-servicing routines do not replace a sys- 
tem interruption-servicing routine? they merely service interruptions 
not serviced by the system. However, a system routine does exist for 
the handling of the SYSIN device attention interruptions. Thus, a user 
must disable the system's servicing routine in order to substitute his 
own servicing routine. He does this by creating the Request Entry and 
Interrupt Control Block with the SIR and SAEC macro instructions respec- 
tively (use of the SAEC macro instruction is restricted to privileged 
programmers when the SYSIN device is specified). These macro instruc- 
tions, provide the user with interruption- servicing routine for atten- 
tion interruptions occurring in his problem program. At this point how- 
ever, two attention interruption-servicing routines have Request Entries 
in the Interrupt Table, the system Attention Handler and the user- 
created servicing routine. Since the system Attention Handler is a pri- 
vileged routine? it has a higher priority RE than the user-created rou- 
tine. Thus, unless the Attention Handler RE is deactivated it would 
continue to receive attention interruptions. 

A user can use the User Attention CUSATT) macro instruction to deac- 
tivate the system-provided SYSIN attention-handling routine thereby 
leaving his lower priority servicing routine in control of handling at- 
tention intermptions on SYSIN. When the user wants processing of at- 
tention interruptions to be resximed by the system, he issues a Clear At- 
tention (CLATT) macro instruction which enables the RE associated with 
the system Attention Handler. 

A second way of establishing user SYSIN attention interruption- 
handling routines for terminals is provided by the AETD macro instruc- 
tion. AETD generates a table containing addresses of routines that are 
to he given control when the user presses the attention key a specified 
number of times. Thus a user may call one or five different attention 
interruption servicing routines depending on whether he presses the at- 
tention key once, twice, or five consecutive times. When using AETD the 
user does not have to set up a Request Entry or Interrupt Control Block 
as when using SIR and SAEC. AETD routines make use of the Request Entry 
for the systems Attention Handler routine. The user routines made a- 
vailable by AETD are in fact made a part of the system's Attention 
Handler routine and remain a part of it until an AETD macro instruction 
with no operand is issued. 

Multi -Level AETD Interruption Routines 

AETD may be specified in a user program that is invoked to handle an 
attention interruption in another program, as defined by an AETD in that 
program, without causing the first AETD to be ignored- AETD macro in- 
structions can be issued at up to ten such levels. However, if mere 
than one AETD is issued in the same program, only the last is reccg- 
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nized. When a program that has issued an lETD exits, the AET entry 
specified by that prograa is deleted. 

On an attention interruption , if there is no AETD for that level of 
program, the user is prompted for input. If an AET entry has been spec- 
ified, the specified routine is given control and the routine exits to 
the interrupted program (the procrraa containina the AETD that specified 
the interruption routine) - 

If the attention key is oressed several times before the command sys- 
tem can process the first interruption, and if no AEI entry is active, 
all but the last attention is ignored. If an AST entry is active, each 
attention routine up to the number corresponding to the number of times 
ATTN was pressed is given control and, except for the last such routine, 
is immediately interrupted by the next queued interruption. As each 
routine exits, the next lower routine is given control until it in turn 
exits; finally, the user proqram that was first interrupted resumes 
control . 

An AjcxD issued at any level with no operand disconnects from the sys- 
tem any AET entry specified in the same Drograii. 

AETD Versus SI5^ SAFC> and USATT 

If SIR, SAEC, and USATT are employed to establish a SYSIN attention 
interruption servicing routine, a user can establish different priori- 
ties for the handling of attention interruptions in relation to other 
types of interruptions. If AETD is used, the user has no control over 
this type of priority specification. 

Another major difference is the recovery abilities for errors occurr- 
ing during the execution of a user-specified attention interruption 
servicing routine. If the routine was established via SIR, SAFC, and 
US ATI, there is no recovery ability and disastrous results may occur, 
lihen the routine is established with AETD^ a user can lyress the atten- 
tion key a number of consecutive times and control will be passed to the 
command systea- The user can then proceed to attempt error recovery 
using the command systeE. 

\ Handling Attentio n Interrupts 

with the inclusion of buffered output support for SYSOUT, a change 

was aade to tae way attention interrupts are handled by TAMIL When a 
user presses the attention key, TA!^II sets a software interlock on the 
terminal to prevent any more reauests from being processed (for the 
user's terminal) until the attention interrupt has been processed. 

TSS con"tains a default (ATTSIiODE) which controls whose responsibility 
it is to reset the attentior. interlock and dispose of any pending I/O 
requests froE the task. ATTNMODE is tet.ted by the task's attention 
interrupt aandler to determine if the interlocK is to be reset fcy the 
systea or i.he attention han.-^^ler. If ]iTTlJSOI)E=OLD the attention inter- 
rupt dispatcher in CZCJ? will issue the TASII macros to reset the inter- 
lock and purge any pending I/O requests. If ATTMf OL»F=NE¥ the attention 
disoatciier assures that the Sl^ed attention routine will take the appro- 
priate action to reset the interlock and to handle any pending I/O 
reguests. 

For handling attention ir.terrupt control, the following TAMII macros 

are available for the user: 

(1) ^o reset the software attention interlock and to restart any 
pending I/U recroests, the I.3NIRL with TYPE = RESTART macro should be used. 
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I (2) If tiie application orogrammer wishes to purge the pendina I/O be- 

I fore resetting the attention interlock, the i>rograEiKer would issue the 

f TCLEiiE with TIiE=ALL lacro. This would cause all pending I/O request? 

I to be purged an^ any associated DSCBs to be marked surged. 

f For further examples on attention han-iling see ABT>enlix N. 
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k??BHDTI J: THT TSS SISTEW MICIO ANDCOPlf LIIvF.^FY 



A symbolic library is conpose-i of a Fvmbolic comoonent and iiiflex com- 
ponent. 'Ihe symbolic component may contain any collection of named 

I groups of symijolic lines called regions; thus, a coliection of ©aero 
definxtioEE corresponding to th.e TSS systeii macro instructions, together 

I with any regions to be accessed by means of the COPY assembler instruc- 
tion, for^ the symbolic coHtPonent of the TSS system aacro and COPY li- 
brary. This library provides the TSS asseaibler ¥ith the macro defini- 

f tions and COPY regions it needs, when systeia macro instructions or COPY 
statements are encountered. 

In xhis library, each macro definixion is a qrouo of symbolic lines 
I whose name (region name) is the same as that of the ooeration of the 

deiinitior's prototype and the corresponding macro instruction. Each 
I COPY region is a group of symbolic lines to whose nan^e a COPY statement 
f must refer, to cooy the reoion into a urogram. The symbolic coaoonent 
of tne system pacro and COPY library is normally cataloged as a virtual 
index secuential data set- The organization and format of this com- 
ponent is shown in Figure 26. The format of each symbolic line, shown 
I in Figure 27, is that of a record in a region data set. The lines of 
information within the symbolic component are ordered by line number- 
I The number of the first line of each reaion is used to index the symbol- 
ic coeporent. 

I The index component is a table that relates the name of each recrion 
I to the number of its first line. Thus^ any region in the system macro 
and COPI library may be located within the symbolic component by aatch- 
ina the operation, of the correspondinq macro instruction or operand of 
the corresponding COPY statement, to the aoDropria-te entry in the index. 
The index component is normally cataloged as a virtual seouential data 
set. It consists of a sinole foriat-U record. 
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Figure 26. Systeni macro and COPY library symbolic component format 



D 

is a z1-byte line whose first character, always a right parenthe- 
I sis, marks it as the delimiter line for a region. The 8-character 

field following the right parenthesis contains the name of the fol- 
f lowing region, left-adjusted with trailing blanks. 

f 1j^, l>2n 

I are synonyas for the followina region. Iny region may have 
synonyms (aliases) . 

I is the jth line of the ktk region; its length is four more than the 
number of bytes given in its length field. 

I Ipte : The first line of a region is 1|P, not D^ . 
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^ . ^ J ^ J , J j_ 

I I EESUME I I II 

\ I 1 \ 1 f- 

I I LL I EN I LN I C I 

I I 1 1 L- 



f 4 bytes 8 Bytes 7 Bytes 1 Byte CLL-16) Bytes 
I figure 27. Format of a line in a region data set 



LL 
f is the length of the lime excluding the four-byte LL field. 

C 

is a code whose values and their faean.inqs are: 

C ode Keaninq 

01 The line originated at a terminal keyboard 

00 The line was obtained as a card image 

Mote: C is normally 00 for all lines of the system macro and COPY 
library . 

I RH 

I is the naiie of the region; must be the same name as the macro or 

I copy contained within the region. 



LM 



is the line number. 

is the text of the symbolic line; its length is sixteen characters 
less than the value specified by LL. 



SYSTEK BACRO AUD COPY LIBRARY SERVICE FACILITIES 

Genera ting the L ibr ary 

I The library may be created and Eodified by using any of the several 
I rss comEands that create line or region data sets. 

Changes are made as a function of line number. Each line in a line 
data set contains a line number; lines in the data set are ordered by 
line number. Once the line data set is created, the user may execute 
SYSINDEX. alternatively r a user's orogram may oerform the reouired 
function by calling SYSJBLD. These routines create the index (CHASLX) 
I which relates the name of each reoion to its first line. ^'hen the Fdi- 
I tor is usei to change the line number of the first line of any region in 
I the symbolic component, an updated index must be created. The use of 
I Editor does not otherwise reauire the subsequent use of SYSIMDFX or 
SYSXBLD. 

Using Symbolic Libraries 

The TSS assembler uses the symbolic library search routine (SYSEIFCH) 
I to locate a reaion in the system macro and COPY library when it encoun- 
ters a system macro instruction or an assembler COPY statement. SYS- 
SAECH inspects the index that the assembler has presented to it, and 
f returns with a return code of '4 if the reauired region is not in the li- 
I brary. If the reguired region is in the library, SYSEARCH returns with 
I the Buaber of the first line of the region and a return code of 0. 
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The assembler 'uses tke lice number obtained from SYSEAECh, in coTx- 
junction with a SETI macro instruct ioE, to position the synbolic com- 
l poneat at the required region. Successive statements are then obtained 
by using the ¥AK GET facility. 

I SISEiiHCE is called to detemine whether the region is present and, it 
I so, positions the symbolic comDonent to xhe desianated region. If the 
I region is not present, exit is made with a return code of 4; otherwise, 

it exits with a return code of - In the latter cape, SYSEHRCH is 
f repeatedly called to obtain successive lines of the region - 

As each line is obtaine^^ , SYSEARCH 'ietensines whether the line is 
\ still in the recuired region by testing the first text character or 
I region name. If that character is a right oarenthesis if the reaion 
I naie is different, or if the EODAD sequence receives control, exit is 
made with a return code of ^; otherwise the line is i>resented to the 
assecibler and exit is made vith a return code of . When the assembler 
is retrieving a macro definition from the library, it will normally 
sense the end of the definition when it receives the definition's FF!*D 
stateaem: . 

If, instead, it detects a return code of 4 before it receives the 
MEND stateaent, it assumes that a library format-error exists. When the 
f asseiiibler is retrieving a COPY reaion , xt relies upon a return code of ^ 
I from SYSEARCh to detect the end of the region- 

Requestin g Sym bo lic Lib rary Servi ces 

Tiie syebolic library ini'exing routine (SISINDEZ) is a system utility 
routine that processes the user's inout parameters. 

The user defines his data sets thus: 

ddei source, vi,libnaiie 
ddef index, vs,nd.xname 

where: libnaine specifies the name tne user wishes to assign to the 
macro data set and ndxname specifies the name the user wishes to assign 
to the index data set. 

The user then issues SYSIHD2X and the system prompts him to enter the 
input parameters. The sequence is: 

sysindex 

SUBMIT COHTEOL ST.%TEME!}T 

header^) ,length=8 

I The control statement is recruested only if the library is not a region 
f data set. The system then prompts the user for the next comiian!. 

Note: SYSIJIDEX does not accept parameters when called. CGCKA will re- 
ceive its parameter via prompting. Users of the SYSINDEX function 
should observe the above seauence- 

The header character is the single character that is compared with 
the first byte of each source line to determine whether that line has an 
index entry. This parameter May be omitted if the user specifies: 

scan=subroutine 

where subroutine specifies the aaiae of a subroutine that is supolied by 
the user; it is called to inspect each successive line of the symbolic 
component. This routine deteraines whether a given line has an entry in 
CHASLX- The SCAN option is not used if the header parameter is 
supplied. 
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Ihe build syifibolic library index roatine C-YSXBLD) constructs the 
iii<2ex portion (C. HASLZ) of trie symbolic library. It is invoked by iseans 
of a CiiLL macro instruction of the following format: 



INaEtt |Oi>eration lO'Deran: 

-4- ^ 



|[syEibol]|C?lLl f SYSXBLD, Clencrth^[ headx^r ][ ,scan]) 



lenath 
I sc>eciries the location of the lenath of reqion names in the 

library . 

Specified as : Reaister notation {Z through 12) , or a relocatable 
expression . 

header 

specifies che location of a characxer used in determinina what 
lines of the syibolic component recruire index entries. Ihe header 
characi-er is compared with the first character of each line to laake 
this determination. If header is given, it must be the second ele- 
ment of the sublist an-l scan must not be given. 

Specified as: Fegister notation {2 through 12) , o^r a relocatable 
expression - 

scan 

specifies the location of an eight-character name of a user's scan 
routine. The name must be lef t-ad:justed and filled with trailinq 
blanks if necessary. The user»s scan routine is called as each 
symbolic line is obtained to determine whether the line requires an 
index ventry . If scan is given, it must be the third element of the 
sublist and header must not be given. 

Specified a s: Hegister notation (2 throuah 12) , or a relocatable 
expression . 

The symbolic library search routine (SYSEA2CH) , used to locate infor- 
mation stored in a symbolic library, is invoked by means of a C^LL macro 
instruction of the followina format: 

I 1 1 1 

I Name f Ooeration f Operand | 

h 1 h- ^ 

|[ symbollfCALL | SYSEARCH , (index ,naiEe, line number) | 
I I I ^ I 

index 

is the address of the index component (CHASLX) of the symbolic li- 
brary to be searched. CHISLX must be brought into storage by the 
user. 

Specified a s; Register notation (2 through 12) , or a relocatable 
expression . 

name 

is the address of the first byte of the name to be located. This 
name must be of the length specified to SYSINDEX or SYSXBLD during 
the creation of the index, and must be left-adjusted with trailing 
blanks. 

S pecified as: Register notation (2 through 12) , or a relocatable 
expression. 
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line nuaber 

is the location at which the SYSIARCH routine is to store the 
retrieval line number it obtains. 

t Specified as ; Register notation {2 through 12) ,, or a relocatable 
I expression . 

R eturn Data : On exit^ a hexadecimal cole will be returned to the call- 
ing program in the return code register. 

C ode Meanincf 
00 The name was located- The retrieval line number will be 
placed in the location designated by the third 
parameter. 
I 04 The name could not be located. 
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TO be ccncurrently accessible to more than one task, a data set must 
have one of the following organizations: 

• Virtual sequential 

• Virtual index sequential 

• Virtual partitioned 

Physical sequential data sets cannot be used concurrently by more than 
one task^ 

To prevent several users from concurrently updating the same record 
of a virtual storage data set, interlocks are put on the data set while 

it is being used. The interlocks, read and write can be imposed at 
three levels: page, data set, or roember. 

Types of Interlocks 

A read interlock is imposed to prevent other users from writing into 
a data set, member, or page of a data set. Multiple read interlocks may 

be established for a data set or member, permitting several users to 
read it simultaneously! or the interlocks may be set on a page basis, 
giving several users simultaneous access to the records within a page.. 
A read interlock cannot be set if a write interlock has already been set 

for the data set, member, or page. 

A write interlock prevents any user, other than the user who set the 
interlock, from reading or writing into a data set, member, or page. 
Only one write interlock can be set at a time; thus, once a write inter- 
lock is set, neither read nor write interlocks can be applied until the 

write interlock is reset. 

Levels of Interlocks 

• Data set interlock - set according to the OPEN option specified, as 
shown in Figure 28. This level of interlock restricts the use of 
subsequent OPEN macro instructions on shared data sets. The inter- 
lock is reset when the data set is closed. 



I 



OPEN 
option 



INPUT 



— + 



OUTPUT 



INOUT 
OUTIN 
UPDAT 



VSAM data set 



read interlock 
set 



write interlock 
set 






write interlock 
set 



VISAM data set 



read interlock 
set 



write interlock 
set 






read interlock 
set 



VPAM data set 
(member level) 



read interlock 
when FIND issued 



write interlock set 
when FIND issued 









— X 



when FIND is issued: 
write interlock is 
set on VSAM members; 
read interlock is 
set on VISAM members 



Figxire 28. Effect of OPEN options on data set interlocks 
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• Member int:erlQck ~ set when the FIND macro instruction is issued for 
a member of a virtual partitioned data set. A ireirber interlock is 
reset when a STOW type-R or CLCSE or FIND iracro instruction is 
issued. 

• Page interlock - set to enstire that the user has exclusive control 
of a record while he is processing it. A page-level interlock is 
reset when a reference is made to another page in the data set or 
when the data set is closed. 

User Considerations 

Ihe only way a user can gain exclusive control of a shared VISAM data 
set is to open it for OUTPUT. Although a data set is opened for CUTPUT, 
a user may actually only want to read the data set. 

When updating a VISAM data set, the record to be updated should have 
been obtained by a READ (type KX> . If users of a shared data set do not 
employ this procedure, two tasks may concurrently refer to the same page 
using either the GET or READ (type KY) macro instructions and decide 
that a record within the page is to be updated. Since both tasks WRITE 
to the same page, the task that issues the last WRITE macro instruction 
cancels the effects of the previously issued WRITE. The following 
sequence prevents this situation: 

GET CD 

decision that updating of the record 
is required 

READ DECB, KX, CI), (0), (2) 

update record 

WRITE DECS, KS, (1> , (0), (2) 

A READ (type KZ) by retrieval address should not be employed by users of 
VISAM shared data sets since the retrieval address cf the desired record 
can be shared by another task. 

Coding sequences within a task may produce task looping that cannot 
be detected by the access method. Consider, for example, this sequence: 

READ DECB, KX, CI), CO), C2) 
GWI (1) 

where the READ and GET macro instructions refer to different DCBs within 
the same task. This situation produces a task loop, since the GET macro 
instruction waits for the write interlock, set by the previous READ 
macro instruction, to be reset. The write interlock will not be reset 
since it was set in the same task that is waiting f cr the write inter- 
lock to be reset. The user must pay close attention to the rules of 
interlock setting and resetting when dealing with multiple opened DCBs 
within a given task. 
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One dotibleword parameter list is generated for each data set DCB be- 
ing opened or closed and placed in a tatle^ as described below s 

byte contents 

0-3 Mdress of the DCB 

4 OPEN/CLOSE option code 

5-7 (00 00 00> 16 

The bit configuratioi^ for the option codes are indicated below. 

bits 0-7 option 

OOXXXXXX another DCB is to be opened or closed 

lOXXXXXX this is the last DCB to be opened or closed 

XXOIXXXX REREAD 

XXllXXXX LEAVE 

XXXXOOOO INPUT 

XXXXllll OUTPUT 

XXXXOOll INOUT 

XXXXOlll OUTIN 

XXXXOOOl RDBACK 

XXXXOIOO UPDAT 
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APPENDIX Ms CONDITIONAL J^SSEMBLY CF MACRO INSTRUCTIONS 



Of t.he macro instructions docaroented in this publication ^ soipe roay be 
assembled only with non -privileged code, while others may be asseirbled 
with either privileged or non-privileged code* The differences in the 
expansions of these two classes of macro instructions lie primarily in 
the types of linkage they develop; those to be assembled with non- 
privileged code assemble with one kind of linkage, these to be assembled 
with privileged code assemble with a different kind of linkage. Other 
macro instructions have no differences in their assemblies.- 

Determination of the type of code to be assembled for a macro in- 
struction is made by examination of a global syirbol that is set by the 
DCLASS macro instruction Cwhich acts as a conditional assembly instruc- 
tion and executes during the assembly) • Prcgrairmers may issue a CCLASS 
USER macro instruction in a privileged module so that they may assemble 
non-privileged code? the global symbol can be reset later by means of a 
DCLASS PRIVILEGED macro instruction^ Similarly, programmers may mani- 
pulate the global symbol to permit assembly of privileged code in a non- 
privileged module. Note that the global symbol in no way affects the 
ability to execute the macro thus assoEtled. However, in many cases, 
code that is generated on the basis of the DCLASS USER option roay not be 
executable in a privileged module; similarly, code that is generated un*- 
der the DCLASS PRIVILEGED option is rarely executable in non-privileged 
modules. 

Figure 29 lists the macro instructions that should be assembled with 
the DCLASS setting appropriate to the type of code to be assembled. 

These macro instructions generate appropriate linkage so that the code 
can be executed correctly, dependent on the setting of the global sym- 
bol. (If O- or P-authority programmers wish to assemble one of the 
macro instructions listed in Figure 29 to be executed in nonprivileged 

code, they should assemble that macro instruction under the DCLASS USEB. 
option.) Figure 30 lists the macro instructions that must be asseffibied 
under the DCLASS USER option Ceither explicitly or 'by default).. The 
macro instructions listed in Figure 31 are assembled without regard for 
the setting of the global symbol? no DCLASS macro instruction need be 
issued to set the global symbol. 
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ABEND 

AETD 

ITINDST 

ATTNEST 

ATTNSAV 

BSP 

CAT 

CDD 

CHCKT 

CHECK 

CLOSE 

CNTRL 

COPYDS 

CSIOP.^ 

DDEF 

DEL 

DELREC 

DIAL 

DIE 

DQDECB 

EEASE 

ESETL 

FEO¥ 

FIND 

FIBDDS 

PINDJFCB 

FREEBUF 

FBEEKAIN 



DEQ 
ENQ 



FREEPOOL 


GATED 


GATWR 


GDV 


GETBUF 


GETDV 


GETMAIN 


GETPOOL 


GTWAE 


GTWRC 


GTWSE 


INTINO 


lOREQ 


LIBESECH 


LPCEDIT 


LPCINIT 


MCAST 


HOTE 


OBEY 


OPEN 


PIEEC 


POINT 


PR 


PRKPT 


PU 


RAE 


READ 


REL 


RELEX 



RELSE 

SAI 

SETD¥ 

SIB 

SOLICIT 

STEC 

STOW 

SYSIN 

TCLEAB 

TCNTRL 

TDCHD 

TFREE 

TGATRD 

TGATWR 

TGATiS 

TGTWAR 

TGTWSR 

TRCBUF 

TREAD 

TWRITE 

TWRTLST 

USAGE 

WRITE 

WT 

WTL 

WTO 

WTOA 

WTOE 



Figure 29. Macro instructions having conditional DCLASS assemblies 



CLATT 

CLIC 

CLIP 



COKKAND 

EXIT 

PAUSE 



STIPER 
TTIMER 
USATT 



Figure 30. Macro instructions requiring DCLASS USER 



[ ADCON 


I ADCOND 


1 ARE 


1 AW All 


1 BPKDS 


1 CALL 


1 CHDERMAC 


1 CHDPSECT 


1 CHDVAL 


f CKCLS 


1 CONSEG 


1 DCB 



DCBD 

DELETE 

DELSEG 

DISCSEG 

EBCDTIME 



EXCSEG 



GETSEG 



GET 

HASH 

LOAD 

MARKRTRN 

PUT PUTSEG 

PUTX 

REDTIM 
RELSEG 



RETURN 

RSVSEG 

SAEC 

SA?B 

SEEC 

SETL 
SIEC 
SPEC 
SSEC 
TRUNC 

VCCW 

VSEND 

XTRTK 



Figure 31. Macro instructions not requiring DCLASS 
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A PPEND IX H: TELECOM MUlfl CAT! ONS AC CESS MET HOD (T AMI I) 



When using TAMII macros, the user Eust be familiar with the effects 
of three TAKII implicit operands which affect the execution of TAMII 
macros* These implicit operands are as follows: 

OUT MOD E= [W IB} 
INMODE={W|B|S) 
CMDRODE= £W|B} 

The default for each of these implicit operands is underlined in the 
expressions above, but may be changed by the DEFAULT command. 

OUTMODE controls the execution of write requests. (See Figure 32.) 
If OUTKODE=W, TAEII waits for the completion of the request before 
returning to the application program. If the request has a DECB 
associated with it, TAMII does not return until the DECB has been 
posted. If OUTK0DE=B, TAKII returns to the application program as soon 
as the request has been scheduled for execution. If a DECB is used, the 
application program must perform a CHCKT to verify the completion of 
write reguests- 



ENTRY 
I 



! OUTPUT I lES 
\ REQUEST? I 



OUTMODE= I — 



\ B 



I USER I 

I PBOVIDED f NO 

I DECB? I 



\ 

I YES 
I 



f SYSTEM I 
I ASSIGNS \ 
I DECB I 



f 



I 



I ISSUE f 
f REQUEST f 
f TO RTAK I 



I ISSUE TWAIT I 
[ ON USER DECB |' 



I USER I 
YES \ PROVIDED | 
1 DECB? \- 



f 



I OUTMODE= I 



I RETURN \- 



I NO 



I ISSUE CHCKT ON SYSTEM DECB f 



B I 



Figure 32. TAMII output request flow diagram (simplified) 
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I RETURN I- 



, YES ■ — NO — • 
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■ f 

I ISSUE WAIT I — ^ 



[ Figure 33. TAMII input request flow diagram (simplified) 
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INMODl coEtrols the completion of read requests. (See Figure 33.) 
If IHMODE=ii, TAMII returns to the application program only after the 
read request has completed^ successfully or unsuccessfully; if a DECB is 
associated with the read reauest^ the return does not occur until the 
DECB has been posted (the same as OOTHODE) - Any read request without a 
DECB, other than TGATBD, is handled as if IMH.ODE=W. If IH!!OVE=S 
Ciaeaning stream input mode) , TAMII tests an input queue for input; if 
the queue is empty and the request does not specify "wait", TAHII 
returns to the caller with a return code denoting no available input. 
If the queue is not empty, TAMII returns the first line of the (jueue as 
the requested input. If a prompt or messaae was associated with the 
request, it is iqnored and not sent to the terminal (TGTWSR is an 
exception to this rule) . 

ISMOBE=B affects different requests in different ways: for example, 
it allows aoplication proqrams to control buffered execution without 
affecting the TSS command system: any request which uses a D^CB is 
overlapped; the SOLICIT macro is enatled and is allowed to execute 
asynchronously to the application program, if supported by the device 
support module. 

When INM10DE=B, TAPII maintains two inout cueues called queue 1 and 
queue 2. Queue 2 holds any input read by a SOLICIT macro; queue 1 holds 
any other asynchronously received input (discussed later under CMDMODE) . 
Queue 2 is called the data oueue and only a TGATRD macro with the 
operand TYPE=A or D (AHI or DATA) can read inout from it; if TYPE=C 
(COMMAND) , the SOLICIT operation is purqed and any data in queue 2 is 
deleted. 

Wnen C]!!DaODE = W (the noraal default) there is no change in the way the 
system works- When CMD!^ODE=B and IHnODE=B also ^ the UFer can enter 
input asynchronously to the task's execution; however, this input is 
sent to queue 1, mentioned above, and can only be read by a TG_«TRD with 
TYPE=A or C. The main difference between IHHODE = S and both I!<?10DE=B, 
CHDHODE=B is the effect UDon the execution of a TGTWAR macro. lith 
IME0DE=3, C;1DaODE=B the prompt or message associated with a TGTWIP is 
displayed for the user; with I3M0DE=S it is not. 

Figure 54 summarizes the effects that the values of II^MODE, OUTfiODE, ar^^ 
CMDMODE have on the various TAHII macros (the macros themselves will be 
described in detail later in this apBendix) . 

MniTIPLE SISIN/SYSOUT SUPPORT 

The application programmer, through use of the CPO and C^I ooerands 
on TAMII macros can direct the macro's action to a specific SYSIN or 
SYSOUT component. If the application programmmer does not cole the 
CPO/CPI operands, the user's settings lor the implicit operancs SYSI!^ 
and SYSOUT determine to which component the TAMII macros will be 
directed. 

For multiple action TAHII macros such as TGTWAR (%ihich involves both 
a write and a read) , different values can be specified for CPO and CFl 
so that a message can be written to the primary SYSOUT and iiput data 
read from a secondary (or tertiary) SYSI'f comDonent . 

The valid values for CPO ansi CFI are given later in the discussions 
of the individual TAMII macros. 
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I Figure 3^. Effects of TAHII implicit operands on TAHII macros 



I ATTENTIOM HANDLING SOPPORT 

TABU provides macros for handling anf crueued requests which may have 
been interrupted by an asynchronous (attention) interrupt from the 
(terminal) user. Through the use of the ATTNDST, ATTNRST and ATTHSA? 
macros, the application progreui^mer has control of any queued recruests. 

After an attention interrupt the pending queue is placed in a hold 
state by TAHII. This hold state can only be reset by the application 
programmer issuing a TCHTRL with TYPB=RESTART macro. Until the PBSTAPT 
request is issued, the application programmer can manipulate the pending 
queue using the ATTHxxx and TCLEAR macros. The ATTHxxx macros may be 
issued after a RESTART, but these macros only affect the pending queue 
and do not interfere with any active requests. 
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The ATTNxr-ix Eacros work on what are callec levels. when the 3TTHSA¥ 
macro is issued , it raves a level of inforiiiatioB conceriimg the oriaary 
SISIH and SYSOUT . Each saved level is assigned a unicue level number 
which is used to identify the level for ase «ith the ATTNK,ST ard iTTNDSf 
macros . 

When the ITTHSAV macro is issued, all cueaed reouests both output and 
input in both the task and the supervisor are ieoueued and saved in 
virtual storaae . Also, all recuest dependent information, for example 
the DECBs, are saved an.d new ones are allocated. After the information 
has been dequeued and saved, a special entry point in the Forpax Conxrol 
Module for the device is called to do any ievice dependent processina. 

To restore a previously saved level, the ATT^iBST macro is issued vi+h 
the level numbers to be restored given as ooerands- Ihe tilling of the 
issuance of the ATTHRST macro is important because it purges any 
currently pending requests before restoring the information from tf*e 
specified level as the current information. Once the restore has been 
comoleted, the terminal is again at the same status as when the save was 
issued- 

The ATTSDS-I Eacro is used to delete unwanted save levels froit the 
ATTNSAV stack. Again, the level number to be deleted or destroyed is 
passed as an input operand to the pacro processor . 

The information saved by the ATTMSAV macro is as follows: 

a- any gueued asynchronous input 

b. any SOLICIT input 

c- any pending requests 

a. the two systes DECBs allocated and used by TSSII 

e. any pending SOLICIT and/or locate mode input inf ormatiori 

f . terminal status information from the work table 

g. specially formatted save area for any queued reguests that were 
queued in the supervisor 

h. any device dependent information saved by the Format Control 
Module for the terminal 

ATTHDST — Delete Saved Attention Leve l (S) 

The ATTNDST nLacro deletes a previously saved user terminal attention 
level- 

I 1 1 1 

fMame ^Operation (Operand I 

I f f— \ 

f[ symbol] J ATTMDST ( LEVIOI}T=nuHiber , LEVLI^ = number I 

I I |[ ,USN=user number ][ ,EF= (I | L| (E, address of L form)}]f 
I 1 I I 

LE¥LOUT 

specifies the address of a fullword containing the nuEber assigned 
to the attention level for the prinarv SYSOUT component that is to 
be deleted, or the value ~1 denoting that all levels are to be 
deleted. 

Specified as : register notation (2 through 12) or an HX address. 

Def ault : none 

LS¥LIN 

specifies the address of a halfworcl containing the number assigned 
to the attention level for the primary SISIN coraoonent that is to 
be deleted r or the value -1 denoting that all levels are to be 
deleted. 
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Sp eciried as: reqister notation (2 t hro^iqh 12) or an EX address. 
Default: none 



USS 



spacities the addr-^ss of a halfword containing the number assigned 

by TAHII to tne user to^ be used for user identification. 



opec ifie l as : register notation (2 through 12) or an RX address - 

Defauxt: user number 0,. the task's owner 

ProGraroF-.inc note : LEVLOUT and LE¥LIM must be ai¥en. 

Initialization : If this macro is to be executed in a privileged module, 
the aost recently issued DCLASS macro in the assembly must have 
specified ?RIVILEG^';d - Jllsor the address of a save area must be Placed 
in register 13 before this macro is executed. 

LeT,urn c ode s: the valid return codes ^ in register 15 ^ are as folloMs: 

C ode F:eani n.q 

1*GQ* successful completion 

X»OiT» invalid level given for lEVLOOT 

X»08« invalid level given for LE?LIH 

>:»0C» invalid levels given for LEVLOUT and LF?1IH 

I" 10" invalid parameters aiven 



ITTHP.ST — Restore Saved .attention Level (S) 

The ATTMRST macro restores a previously saved attention level < 



fHame | Operation f Operand 
-i h 



f [ symbol ]( ATTNRST f LEVLOOI=nuiiber ,LEVLIN = nuiEber 

I \ |[ /JSl!i = user number ][ ,MF=CIf LI (E, address of L form)}] 



LEVLOUT 

s-»>ecifies the address of a fullword containing the nuRber assigned 
to the attention level for the primary SYSOUT component that is to 
be restored . 

Sp ecifi ed, as: register notation (2 through 12) or an PX address. 

Default : none 

LE¥LI13 

soecifies -the address of a halfword containing the number assigned 
to the attention level for the primary SYSIN component that is to 
be restored - 

Specified as ; register notation (2 through 12) or an EX address. 

Default: none 



USN 



specifies the address of a halfword containing the nniiber assigned 
by lAKII to the user to be used for user identification. 

Spe cified as : register notation (2 through 12) or an PX address. 

Default : user number 0^ the task's owner 
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I ProqrammiBq note : LEVLOOT and LEVLIH must be given. 



Initialization : If this macro is to be executed in a privileged module, 
the most recently issued DCLASS macro in the assembly Eost have 
specified PRIVILEGED. I. Iso, the address of a save area must be placed 
in register 13 before this macro is executed. 

Return codes : the valid return codes, in register 15, are as follows: 

C ode Meaning 

X'OO" successful completion 

X»04» invalid level given for LEVLOOT 

X»08« invalid level given for LEVLI!i 

X»OC» invalid levels given for LEVLOUT and LEVLIH 

XMO» invalid parameters given 

AT TMSA ? — Save Current Oser Te rmina l Informat ion CS) 

The ATTNSA? macro saves current tersainal information so that it can 
be later restored for normal processina after an attention interrupt has 
been processed. ATTSSAV saves information about the user's primary 
SISIN and SYSOUT only; secondary and tertiary components are not 
supported. Op to ten saves can be recorded in a TAMII push down stack. 

I 1 1 1 

I Name | Operation f Operand f 

h 1— \ ^ ! 

|[syabol]rATTHSAV f[,USM = user number ][, Mi = (I | L | (E, address of L form)}]| 

I I I , 1 

OSN 

specifies the address of a halfword containing the nuiLber assigned 
by TAMII to the user to be used for user identification. 

Sp ecified as: register notation {2 through 12) or an BX address. 

Def ault : user number 0, the task's owner 

Initialization : If this macro is to be executed in a orivileqed module, 
the most recently issued DCLASS macro in the assembly Eust have 
specified PRIVILFGED- Also, the address of a save area must be place3 
in register 13 before this macro is executed - 

B e turn c odes : upon completion of an ATTKSAV execution, recisters and 
1 contain the save level numbers for SYSOUT and SYSI'^ respectively. 
Begister 1 contents may be zero which means that the SYSODT and SYSIM 
are the same (device) and only one level was created (saved) . Also, 
register 15 contains a return code as follows: 

Code Rean ing 

X"00" successful completion 

X"04« iLaximuffi levels for SYSOUT reached 

X»03» maximum levels for SYSia reached 

X«OC« maximum levels for SYSIN and SYSOUT reached 

X»10' invalid parameter list or address 

CH CKT — Check C o mpletion o£ TAail DSCB [§1 

The CHCKT macro is used by TAJIII applications to check the coiipletion 
status of those Thfill recuests for which the aDplication program 
specified a DECB. 
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I Name | Operation | Operand 

I- 1 1 ^ ^ 

I [ symbol ]|CHCKT IDECB=decb address [ ,USN=user number address] 

I I |[ ,WAIT={ISSf WAITfNOfNOWIIT] ] 

I I |[ /riPE=CT|TWAITf AIAWAIT} ] 

I I |[ ,KF= {II L I (Headdress of L form)}] 

I I t , 



BECB 

identifies the 48-byte DECB area to be used by TAKII. 

decb address 

address of the DECB to be marked upon completion of the DIAL 
request. 

Specified a s: register notation (2 through 12) or an BX address. 

Defaul t: none 

USN 

the number assigned by TAEII to be associated with the connected 
terminal that is to be scheduled for the requested operation. 

Specified as : the address of a halfword in register notation (2 
through 12) or an RX address. 

Default: user number 0, the task's owner. 

WAIT 

determines if CHCKT is to wait for completion of the request. 

Specified a s : 

YES or WAIT - CHCKf waits for the DECB to be posted before 
returning to the caller. 

NO or NOiAIT - CHCKT returns immediately to the caller, whether the 
request has completed or not; the user must test the return code to 
determine the status of the request. 

Defaul t: YES (WAIT) 

TYPE 

determines the type of wait if the WAIT operand is specified as YES 
or WAIT. For n on -privileged programs, this operand is ignored by 
TAMII and a TWAIT is always done. For the privileged routine, this 
operand may be used to allow the program to synchronize with the 
system •s schedule table. 

Specified a s : 

T or TWAIT - a TWAIT SVC will be used. 

A or AWAIT - an AWAIT S ¥C will be used. 

Defaul t: T (TWAIT) 

I nitialization ; If this macro is to be executed in a privileged module, 
the most recently issued DCLASS macro in the assembly must have 
specified PRIVILEGED. Also, the address of a save area must be placed 
in register 13 before this macro is executed. 

Programming note ; TAHII overlaps requests using DECBs only if the 
implicit operand INMODE^B or S and/or OOTMODE=B. All output only and 
control requests are governed by the OUTMODE operand; all input requests 
are governed by the INMODE operand. The combination requests such as 
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TGTWIR and TGTiSR which perform a write and a read are governed by the 

INHODE operand. 

B etu rn code s: the valid return codes for a CHCKT request are in 

I register 15 (byte 3) as follows: 

Code Meaning 

X»00» request completed successfully. If input data is expected, 
register contains the data length and register 1 contains 
the data address. Also, Register t5 may contain return codes 
in bytes and 2 which describe the input record. If byte 
of register 15 is X»30' the input is in cardboard format; if 
byte is X»00« the input is in keyboard format- Byte 2 may 
contain one of the following values: 

X'OO* - normal input 

I "01* - record ends with a continuation character 
X»02" - record truncated to fit user's input area; the 
rightmost characters have been lost 

X»04« request is active and HOWAIT was specified. 

X*08» attention was received on request. If input was expected 

register contains the input length and register 1 contains 

the input address. 
X9QQ9 ^i^e CHCKT request was not processed due to a pending 

attention. 
X*10* request was purged by a TCLEAR macro. 
X»14« invalid for CHCKT. 
X»18» error in the CHCKT parameter list (probably an invalid or 

inactive DECB address) • 
X»1C» xnvalid for CHCKT. 
X«20« invalid for CHCKT. 
X»24« terminal disconnected. 
X*2&* permanent I/O error on request; sense is valid and is from the 

last retry . 



D IAL — DIAL a Specified Tel ephone H umber (S) 

The DIAL macro activates and executes a call-out sequence, using the 
hardware auto-call unit, to connect a specific terminal. 



I 

I Name 



1 ^ ^ — ^ 1 

Operation f Operand f 



I [symbol ] 

f 

f 

I 

i 



DIAL fOUTADDR=dial digit address, OUTLGH=number of digits f 

|,DECB={decb address| (name,!) } [,0SN=user number] f 
f[ ,CPO=sysout number ][ ,CPI=sysin number] | 

|[ ,HF={If If (S, address of L form))] | 

, 1 1 



OUTADDR 

address of an area containing the digits to be dialed. The digits 
must be a full telephone number in EBCDIC form. 

Specified a s: register notation (2 through 12) or an RX address. 

D efaul t: none 

OUTLGH 

address of a fullword containing the number of dial digits pointed 
to by OUTADDR. 

Specified a s: register notation (2 through 12) or an RX address. 

Defaul t; none 

3 16 
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DECB 

identifies the ^8-byte DECB area to be used by TAMII* 

decb address 

address of the DFCB to be marked upon completion of the DIAL 
request. 

Specified a s; register notation (2 through 12) or an RX address. 
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De faul t : none 

n a m e 

the naipe, label or symbol to be assigned to the DECB. 

Spec ifie d as: one to eiglit characters, the first of which aiust be 
alphabetic. 

Default : none 

f 

sianiiies that the DECB area is to be constructerl. as part of the 
macro expansion, iHntediately followina the parameter list. 

address of a halfword, containing the nuiaber of the user for which 
the DIAL recuest is beina made. 

Spe cifie d as: register noration (2 throttgh 12) or an PI address. 

Default : user number 0, the task^s owner. 

address of a half word containing the number for the user's SYSOOT 
for which the DHL reauest is beina made. 

Spec ifie d as: register notation (2 throuah 12) or an RX address. 

Default: the value in the default SYSOLT. 

address of a half word containing a number of the specified user's 
SYSIN for which the DIAL request is being made. 

Specified a s: register notation (2 through 12) or an EX address. 

Def ault : the value in the default SYSIN- 

Init iali z ation ; If this macro is to be executed, in a privileged module, 
the most recently issued DCLASS macro in the assembly must have 
specified PSIVILEGED. Plso, the address of a save area must be placed 
in register 13 before this macro is executed. 

Programming not es: CPI or CPO may be soecified, but not both. 
Specifying both does not cause an assembly error, but lAMII will return 
a user error code upon execution of the DIAL macro. DIAL may be used 
for a coEiiiunication line that has been sysgened with the auto-call 
feature, but if not sysgened, TAMII returns the unsupported device code. 

Feturn c odes : the following are the return codes, in register 15 
following the execution of either the DIAL macro, or the CHCKT macro for 
the DECB assigned to the DIPL request. 

Code Meanin g 

X»00« successful reouest 

X*18» user error in parameter list 

X»20' line does not have autocall feature or device support 

module does not support a DIAL reguest 
X»2il« permanent error on DIAL 
X'23» permanent error on DIAL 

SO LICIT — Read from Sp e cified SYSI!i with Prompt (SI 

Ihe SOLICIT macro reads data input from a specified SYSIN. Each read 
reguest may be preceded with a given prompt or an incrementing number. 
The SOLICIT reguest is ended by the user entering a command break 
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character, a null line, by an incrementing prompt reaching an ending 
bound, or a line count going to zero. 

I 1 1 

[Name | Operation! Operand 

4 



1 r 

[ symbol ] \ SOLICIT | TYPE= {C J B f S f D} , US H=user number , SIC= £SIC M I 2} 
I I ,CPI=sysin number [ ,NULL= (Y | N] ] 

f [ ,PRMPT=prompt value, LE]SG=prompt "• — ^--^^ ■» 

([ ,I!JCR=Drompt increment ,E!ID=promp 

I [ ,SOM=nuiiber of lines to read] 

f ],MF=fI|L MS, address of L form)}] 



! 

f ([ ,I!JCR=Drompt increment ,E!ID=prompt end value] 

I 

I 



USN 



SIC 



TYPE 

specifies the type of t>rompt to be used. 

Specified a s: M - no prompt 

C ~ character prompx, no incrementing allowed 

D - number prompt given in packed decimal 

B - number prompt given in binary 

Default : H (no prompt) 

the number assigned by TUMII to be associated with the connected 
terminal that is to be scheduled for the recuested operation. 

Specified as: the address of a ha If word in register notation (2 
through 12) or an RIC address, or *ALL . If specified as *iiLL, or if 
the half word value is set to X«PFFF», all connected KTT' users 
SYSIH/SYSOUTs will be scheduled for the reouested operation . 

Default : user number 0, the task's owner. 

a code identifying the level of translation and editing to be done 
on the input data. 

Specified as : 

SIC - data to be translated but not edited 

1 - saae as SIC 

2 - data to be passed untranslated and unedited 

Default: input data will be edited and translated. 

the SYSIN component for which this reauest is to be executed. 
Sp ecif ied as: 

- uses the value in the default SYSIN. 

1 - uses the primary SYSI^. 

2 - uses the secondary SYSI!I- 

3 - uses the tertiary SYSXl. 

D efault : uses the value in the default SYSIH. 

NULL 

specifies whether or not a null line ends the SOLICIT reCTuest. 

Specified as : Y (yes) or H (no) 

Default: ^ 

PEMPT 

specifies the address of the prompt value to be used by the SOLICIT 
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I reguest when soliciting input. For TIPE=C the address is that of 
I the prompt character string; INCB and END are ignored. For TYPB=D 
f the address must point to a valid packed decimal number whose 
I length is four bytes. For TYP£=B the address must point to a 
I fullword containing the starting prompt value. For TIPB=D or B, 
\ STAM converts the value to a printable number of the format 

I MNNNMMHb where H is an EBCDIC digit; the number is right- justified 
I and padded with zeroes to make the seven digits. 

I Specified as : register notation (2 through 12) or an EX address. 

f Defaul t: none 

f LBNG 

I specifies the address of a fullword value containing the length of 

I the prompt value. If PRBPT is given ^ LENG must be given. 

I Specified as: register notation (2 through 12) or an HX address. 

I Defa ult : none 

f IHCR 

I specifies a fullword containing either a packed or binary number 
I that is to be added to the prompt value after every successful read 
I completion. The type of IMCB (packed decimal or binary) niust agree 
I with the TYPE operand. A length of four bytes is assumed. 

I Specified as : register notation (2 through 12) or an EX address. 

I Def ault : none 

\ SKD 

I specifies a fullword containing either a packed decimal or binary 

f number that is to be used as a stop value for incrementing a 

I prompt. The SOLICIT is ended when the prompt value eguals or 

f exceeds the given END value. The type of EHD must agree with the 

I TYPE operand. A length of four bytes is assumed. 

I Specified as: register notation (2 through 12) or an FX address. 

I Def ault : none 

f Bun 

\ for TYrB=C or IJ, soecifies a fullword containing the number of 

I lines to be read froE SYSIN . The SOLICIT will be ended when the 

I specified number of reads has been completed. The value is treated 

I as an unsigned 32-bit logical number. 

I Spe cified as : register notation (2 through 12) or an RX address. 

\ De fault : none 

? Initialization : if this macro is to be executed in a Privileged module, 

I the ikost recently issue! DCLISS macro in the assembly must have 

f soecified PRI?ILFGFD. Ilso, the address of a save area must be placed 

I in register 13 belore this Bacro is executed. 

\ Return codes: The valid return codes, in register 15, are as follows: 

f Code Meaning 

I X»00* successful reauest 

I A»18» user error in parameter list 

I p rograiEjikinq not_e: TAKII suT>ports the SOLICIT macro- for all SYGINs. 
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I TCLEAR - — I-urcie Pending & Act ive I/O Recaestg (S) 

Ihe 'iCLEAE macro TBurges all or specific types of I/O requests froi!! 
the scheduled and active re<Tuest queue - 

I ^ 1 1 

I II am e | Operation | ODerar.l 

I- 1- \— 

f[sYi*boi]fTCLEAR |TYPE=[A or ALLfO or OOTPUTfS or SOLICIT f 

I I I or INPUT ID or BECB} 

I f [ ,DECB= fdecb address| (name, Y) } 1[ ,USl«=user number} 

I f [ , {CI'I=sysiB number fCF0=syFOUt nuiiber} ] 

I ir ,?5F= (I ILf (E, address of L form)}] 

I i i 

TYPE 

ideritixies the request (s) to be ourged . 

Specif ied_ as : 

A or All - purge all ascheduled and acrive I/O , and release any 
buffered input records . 

or OUT"^!JT - i>urqe all scheduled and active transmissions. 

S or SOLICIT - Durge the current SOLICIT request and any iFput 
records read by the SOLICIT request. 

1 or III PUT - purge all pending input records and all currently 
active input I/O. 

D or DECB - purge the reauest using the given DECB address - 

Default: none 

DECB 

for TI?E=D or DECB only; specifies the address of the DECB xo be 
purged- 

Spec ifie d as: register notation (2 through 12) or an FX address. 

Default: none 



OSU 



CPI 



CPO 
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the number assigned by TAfll to be associated with the connected 
terminal that is to be scheduled for tne reguested operation. 

Spe cified a s: the address of a half word in reoister notation (2 
through 12) or an PX address, or *ILL- If specified as ^-ILL, or if 
the halfword value is set to X'FFFF', all connected KIT users 
SYSI!sl/SYSOUTs will be scheduled for the reouested operation. 

Def ault : user number 0, the task's owner. 

the SYSIN component for which this reguest is to be executed. 
Spec ified a s : 

~ uses the value in the default SYSIN. 

1 - uses the prinary SYSI^ . 

2 - uses the secondary SYSIN . 

3 - uses the tertiary SYSIN. 

Default: uses the value in the default SYSIN - 

the SYSOOT component for which this request is to be executed. 
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Specified a s: 

- uses the val\ie in the default SISOGT. 

1 - usef^ the primary SYSOUT. 

2 - uses the seconlary SYSGUT. 

3 - uses the tertiary SYSOOT. 

Default: uses the value in the default SISOOT. 

Initialization: If this macro is to be execute3 in a privileged module, 
the EOSL recently issue! DCLISS macro in the assembly must have 

specxfied l-RIVILEGED . IIso, the address of a save area roust be placed 

in register 13 before this macro is executed. 

Progra EiBinq note: the use of the CPO or CPT operand must be consistent 
tfith the TYPE specified; for example, specifying TYPE=0 and specifying 
CPI (insxead of CPD) results in the default SYSOUT being purged and CPI 
is ignored - 

After issuing tne ICLEIR macro for a soecific DECS, the DECB may then be 
reused witiiout issuing a CHCKT Fiacro. 

Return codes : the vali-i return codes, in register 15, are as follows: 

Code Meaning 

X»00» reguest completed successf ully - 

X'lB* error in parameter list, invalid DECB pointer, or OSI, CPO/CPI 
is invalid 

-TC^T RL — Trans aiit a Cont r ol Reques t, JS) 

The ICIjlFL macro transmits a control-tyoe reguest to either TAMIT or 
to a node or terminal; it is not normally used for data transmission - 

J 1 J ^ ^ ^ ^ J 

fSame | Operation | Operand 

1 , ^ 

|[syiikbol]fTCNTRL | TYPE= (BELLf INHIBIT | THSTRT or RESTART |ERASE J 

I r ENABLE or DROPf DISABLE or HOLD f PREPARE f 

I I SETCITPSRIENABINP} 

I |[ ,O0TADDR=data address ][ ,OUTLGH=data length addr] 
f |[ , CCPO=sysout number fCPI=sy sin number}! 
I |[,USN=user number ][ rDECB= (decb address Hnaie ,Y) } ] 
\ |[ ,!1F=CI fL| {E, address of L form)}] 
I I 



TYPE 



specifies the control operation to be performed. 

Spe cified as : 

BELL ~ causes the alara-bell located on the device to be rung. If 
the alarm bell does not exist but is valid for the device type, the 
reguest is ignored by the hardware. If the reauest is invalid for 
the device type, a code indicating an unsupported device is 
returned . 

IHRIBIT - causes TAF!II to set a software device interlock so as to 
prevent normal I/O to the terminal- High priority requests {BEK=Y> 
override this interlock. 

TRSTRT or RESTART - causes TAHII to reset the software device 
interlock and to resume any pending I/O requests. 

ERASE - causes the screen on a display terminal to be erased and 
the cursor to be positioned to row 0^ column 0. 
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ENABLE or DROP - causes the terminal line to be enabled to accept 
incoming terminal connections or calls. 

DISABLE or HOLD - causes the coaimiiiiication line to be reset and not 
accept any incoming terminal connections or calls. 

(Mote: the routine using this macro ¥ith an ENABLE or DISABLE tyoe 
code must be privileged and must have issued a BCLASS PRIVILEGED 
macro before using these code types on this macro.) 

PREPARE - causes an enabled line to be monitored for any terminal 
activity - 

SETCOPSF - causes the cursor on a display screen to be positioned 
at a specific buffer address. 

EHABIHP - causes a display terminal keyboard to be unlocked and 
input enabled. The cursor is positioned at the address in the SHDR 
control block . 

(Note: TYPE=SETCURSR or ElABINP reguires a SHDR control block as 
output; refer to the lerminal User's Guide.) 

Default : none 

The device supported type codes are as follows: 



TYPE 



I 2741 I TTYs I 3215 \ 3270 | 3066 | 



\ BELL 1 NS f S 1 S f S 1 S f 
1 IHHIBIT 1 S 1 S 1 SI S f S \ 
1 TRSTHT 1 S 1 S 1 S 1 S f S | 


1 P.ESTAFT 1 S 1 S 1 SI S | S | 
1 ERASE ! NS 1 NS 1 NS f S | S | 
f SUABLE f S f S 1 !iS 1 »S 1 NS 1 


I DHOP I S 1 S 1 NS 1 NS 1 NS 1 
1 DISABLE \ S f S 1 ^S 1 !IS 1 NS 1 
I HOLD 1 S \ S i NS 1 HS 1 NS 1 


1 PREPARE 1 S 1 S f HS 1 NS 1 NS 1 
1 SETCUBSE 1 NS 1 HS 1 NS f SI S f 
1 EMBINP ! NS 1 NS 1 NS I S | S | 



[ H=SUPPOFTED; l!S=IIOT SUPPOBTED 



OUTADDR 

address of the dara to be trai^smitted from the apBlication. 

Specified a s: register notation (2 through 12) or an EX aidress. 

Default: none 

OUTLGH 

the length of the data pointed to by OUT&DDF; maxiaum length is 
4000 bytes. 

Specified as : the address of a fullword in register notation (2 
through 12) or an RX address . 



USN 



Default: none 



the number assigned bv TAflll to be associated with the connected 
terminal that is to be scheduled for the requested operation - 
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Specified a s; the address of a halfword in register notation (2 
through 12) or an BX address, or *1LL. If specified as ^hLZ, or if 
the kalfword value is set to X»FFFF», all connected MTT users 
SYSIM/SYSOUTs will be scheduled for the requested operation. 

Def ault ; user number 0, the task's owner. 

CPO 

the SISOUT component for which this reguest is to be executed. 

Specified as : 

- uses the value in the default SYSOOT. 

1 - uses the primary SYSOOT. 

2 - uses the secondary SYSOUT. 

3 - ases the tertiary SYSOUT. 

De fault ; uses the value in the default SYSOUT. 

the SYSIN component: for which this reguest is to be executed. 

Specified as : 

- uses the value in the default SYSIN. 

1 - uses the primary SYSI5I. 

2 - uses the secondary SYSIM. 

3 - uses the tertiary SYSIN. 

Default : uses the value in the default SYSIN. 

DECB 

identifies the 46-byte DECB area to be used by TAMIL 

decb address 

specifies the address of the DECB 

Sp ecified a s: register notation {2 through 12) or an RX address. 

Deiault : none 

name 

tue came, label or symbol assigned to the DECB. 

Spec i€i e:J as : one to eight characters, the first of which must be 
alphabetic. 

Def ault : none 

Y 

signxiies that the DFC5 area is to be constructed as part of the 
macro expansion , immediately followinq the parameter list. 

Note : before using a D3CB area rA!!II checks to determine that the area 
is available for use, that is, the area is not being used by some other 
reguest; if not in use, it clears all U8 bytes of the previous DECB. 

In itial i zat ion : If this macro is to be executed in a privileged module, 
the aost recently issued DCLISS macro in the assembly must have 
specified FRIVILEGED. Also, the address of a save area raust be olacei 
in register 13 before this macro is executed. 

ProgramEiinq note: privileged routines Rust have the address of a 
76-byte save area in reaister 13 before executing this macro. 

I Heturr4 c ode s: the valid return co?!es, in register 15, are as follows: 
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Code Feaninq 

y^OO* request started ruccess fully 

X 104 11 device busy ,reaiiest scheduled 

X*08' attention received on this reauest 

X'OC'i request not processed due to peiidinq attention 

XMO*i request uarqed by a TCLEAS reouest 

Xn4» invalid for TCRl'FL 

X"18' error in user's parameter list 

X«1C« invalid for TCilTEI 

X*20' requested operation is not supporred. on this device 

X»24» terminal has disconnected 

X«28** permanent I/O error on reeuest 

I'lhese return codes are invalid tor TYPii^IimiBIT or TBSTFT or 
RESTABf . 

TDCMD - - Trans mit Device Control Comiaands (S) 

The TBCMD macro is used by apolication programs for sending Device 

Control Coamands to the Device Control Comnand module - 

J — , 1 ^ 

IHame | Operation) Operand 

\ 1 »— 

|[syBbol]|TDCMD |[ oyTADDB=ciata address ][ ^OUTLGH=data 

I f |[ , {CPO=^sysout number fC?I=sysin number}] 

I f r[,USN=user number ][ ,HF={I»L| (E, address of I form)}]! 

I I I 

OUTIDDI^ 

address of the data to be transmitted from the at>plication . 

Specified a s: register notation (2 through 12) or an EX address. 

Def aul t: none 

OCTLGH 

the length of the data pointed to by OUTADDB ; maximum lenoth is 
4000 bytes. 

Specifie d as: the address of a fullword in register notation (2 
through 12) or an RX address. 

Default: none 

the SYSOUl* componenx for which this request is to be executed. 
Specified a s; 

- uses the value in the default SYSOUT. 

1 - uses the primary SYSOOT. 

2 - uses the secondary SYSOOT. 

3 - uses the tertiary SYSOUT. 

Default : uses the value in the default SYSOUT. 

the SYSIN component for which this request is to be executed. 
Specified as : 

- uses the value in the default SYSIN. 

1 - uses the primary SYSIHI. 

2 - uses the secondary SYSIN. 

3 - uses the tertiary SYSIN. 
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Default: uses the value in the default SYSIM. 



us:i 

the naittber assigned b¥ TAFII to be associated with the coBnected 
terainal that is to be scheduled for the requested operation - 

Specifie d as: ithe address of a halfword in register notation {2 
through 12) or an ^X address^ or *ltLL. If specified as *ALL, or if 
the half word value is set to X"FFPF», all connected KTl users 
SYSI'f/SYSOUTs will be scheduled for the recuested operation. 

Default: user number 0, the task's owner. 

Initialization : If this macro is to be executed in a privileaed module,. 
the most recently issued DCLJISS macro in the assembly must have 

specified PRIVILFGED. Also, the address of a save area must be placed 

in register 13 before this p.acro is executed. 

PrpgraM K.inq not e: either CPO or CPI should be given; if both are given, 
CPO is ianored and C?I is used. If CPI is not aiven, the reouest will 
be issued to the SYSOUT specified by CPO, or to the default SYSOUT if 

CPO is also not given - 

h eturn c odes : the valid return codes, in register 15, are as follows: 

Code F^eanin q 

X*00» successful recruest 

X»18» invalid coRDiand or parameter in request 



i'FRES — Disconnect a User or Component (S) 

The TFREE macro disconnects a user or users from a task. 

^ ^ — _ ^ ^ ^ ^ — I _ — ^ ^ .^ ^ — __ — ___ — . — _ ^ . ^ 

Name [Operation! Operand f 

t— ^ f 



[syaibol jITFHEE f[USN=user number ][ ,TY?E= fPHD f LOG] ] 

f |[ ,OOTADDR=data address 1[ ,O0TLGH=data length addr ] | 

I |[ , {CPO=sysout nuaber|CPI=sysin nurober} ] | 

I |[ ,MF= {I |Lr (E, address of L form)}] | 

L I . I ■ ^ i 

USN 

the number assigned bv TAHII to be associated with the connected 
terminal that is to be scheduled for the requested operation. 

Sp e cified as: the address of a half word in register notation (2 
through 12) or an FX address, or *1iLL. If specified as *ALL, or if 
the haifword value is set to X'FFFF*, all connected MIT users 
SYSlH/SYSOUTs will be scheduled for the requested operation. 

Def aul t: user number 0, the task's owner. 

TYPE 

specifies the type of disconnect to be performed. 

Spec ified as : 

PKD - physical disconnect; user cancot reconnect. 

LOG - logical disconnect; user has two minutes to LOGON or 
reconnect to an application task. 

Default : none 
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OUTIDDE 

address of the data to be transmitted from the application. 

Specified a s; register notation (2 through 12) or an IX address. 

Default: none 

OUTLGH 

the length of the data pointed to by OUTADDR; maximmm length is 
4000 bytes. 

Sp ecified a s; the address of a fullword in register notation (2 
through 12) or an RX address. 



CPO 



CPI 



Default ; none 

the SYSOUT component for which this request is to be executed. 
Specified as : 

- uses the value in the default SYSOUT. 

1 - uses the primary SYSOBT- 

2 - uses the secondary SYSOUT. 

3 - uses the tertiary SYSOUT. 

Default : uses the value in the default SYSOUT. 

the SYSIX component for which this request is to be executed. 
Specified a s: 

- uses the value in the default SYSIN. 

1 - uses the primary SYSI»I. 

2 - uses the secondary SYSIN. 

3 - uses the tertiary SYSIS. 

Default : uses the value in the default SYS IS. 

Initialization : If this macro is to be executed in a privileqei module, 
the most recently issued DCLASS macro in the assembly Eiust have 
specified PRI'VILEGED. Also, the address of a save area nust be placed 
in register 13 before this macro is executed - 

ProqraaBii nq not es; OUr^DDF and OUTLGH are used to send a message to the 
user/component at the time of disconnection, but these operands are 
ignored for SYSIU components. 

I£^ USN only is given, the user is completely disconnected from the 
application. If CPO or CPI is also given, the specific coiponent is 
disconnected. If the CPO or CPI has more than one node connected, only 
the top active node is disconnected. 

If a specific node is connected as both a SYSOUT component and a 
SYSIN component, and TPRKE is issud against either component, the node 
will be disconnected froai both components. 

Keturn codes : the valid return codes, in reaister 15, are as follows: 

C ode lieani nq 

X'OO* successful request 

)C'18» error in user's parameter list 
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TGATHD -- Get a Pecord from Spec ified SISIN (S) 



The TGATBD macro retrieves a record from a specified SYSIN and makes 
the data available to the application program. 



I 1 1 

I Name | Operation | Operand 



^[symbol JIIGATHD fINADDB=data address, INLGH=data length address 
I f |[ ,KODE={M|L} ][ ,SIC={SIC| 1 12} ][ ,USH=user number] 

I I r[ rTYPE={C|D|I} ][ ,WAIT={Y|N} ][ ,CPI=sysir. number] 

I f |[ ,MF=CIf Lf (E^address of L form)]] 

I I I . — 



INADDR 

address of the area to receive data to be sent to the application. 
This operand is not required if MODE=L. 

Specified a s: an address in register notation (2 through 12) or an 
RX address. 

Defaul t: none 

IMLGH 

the length of the data pointed to by INIDDR; maximum length is 4000 
bytes. This operand is not required if MODE=L. 

Specifie d as; the address of a fullword in register notation (2 
through 12) or an BX address. 

Defaul t; none 

MODE 

specifies how TIMII is to handle the input area. 

Specified as ; 

M - input data is moved in to the user-provided area indicated by 
the IHADDR and INLGH operands; on return, register contains the 
length of the data and register 1 points to the input area. 

L - input data is placed in a system allocated buffer; on return, 
register contains the length of the data, and register 1 points 
to the buffer. The buffer is released after the next request to 
schedule input is received. When F.ODE=L, INADDR and INLGH are 
ignored, if specified. 

Default: M 

a code identifying the level of translation and editing to be done 
on the input data. 

Specifie d as : 

SIC - data to be translated but not edited 

1 - same as SIC 

2 - data to be passed untranslated and unedited 

Defaul t; input data will be edited and translated. 

the number assigned by TAMII to be associated with the connected 
terminal that is to be scheduled for the requested operation. 

Specifie d as; the address of a halfword in register notation (2 
through 12) or an RX address. 

Defaul t: user number 0, the task's owner. 
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TYPE 

specifies the type of input data to be read. 

Specified a s: C - command input 
D - data input 
A - any available input 

Defaul t: k 

specifies whether or not the task waits for a read completion 
before returning to the caller. 

Specified a s; Y (yes) or M (no) ; if specified as H and no data is 
in the queue, an X»1C" code (no input available) is returned to the 

application program. 

the SYSIN component for which this request is to be executed. 

Specifie d as : 

- uses the value in the default SYSIN. 

1 - uses the primary SYSIN. 

2 - uses the secondary SYSi:i. 

3 - uses the tertiary SYSIN. 
L - uses the internal queue - 

Defaul t: uses the value in the default SYSIN. 

I nitializatio n : If this macro is to be executed in a privileged module , 
the most recently issued DCLAS3 macro in the assembly must have 
specified PRIVILEGED. Also, the address of a save area must be placed 
in register 13 before this macro is executed. 

I Iv eturn code s: the valid return codes, in register 15 (byte 3) , are as 

follows: 

£ode Meaning 

X«00* successful completion. Also, Register 15 may contain return 
codes in bytes and 2 which describe the input record. If 
byte of register 15 i& X"80» the input is in cardboard 
format; if byte is X»00» the input is in keyboard format. 
Byte 2 may contain one of the following values: 

X»0-0» - normal input 

X»01» - record ends with a continuation character 
X»02» ~ record truncated to fit user's input area; the 
rightmost characters have been lost 

X*04« device busy, request scheduled 

X*08* attention received on this request 

X«OC* request not processed due to pending attention 

X*10® request purged by a XCLEAl request 

xn^* EOD on a SOLICIT request 

XM3* error in user^s parameter list 

X*1C« no input available to fulfill request 

X«24« terminal has disconnected 

X*28* permanent I/O error on request 

T GATyjR - - Put a Reco rd o n Specif ie d SYSOUT (S) 

The TGATWR macro instruction schedules a record to be transmitted to 

a specified user's SYSOUI. 
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INaET.e lOp 
I 1 
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on f Operand f 
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1 [ symbol j|TG 
1 1 
f 1 
1 t 
1 \ 


HTWK 




1 ■ 1 

|[ODTADDI<=data a-:tdress ][ ,0UTLGH=<3ai:a lenath addr ] | 
If ,SIC= CSICHI 2} ][ ,OSN = UFer number] | 
([ ,DECB= {decb address f (name, Y) } 1[ , CPO=SYso-at number]! 
|[ ,BRK=CY|5} ][ ,CC-CY|S] ] 1 
|[ ,MF=CI ILI (E, address of L form)}] f 



Sote: it the E and L form pair of this macro is ns.e^. the SIC, BRK , and 
CC ooeraiids must be specified on the E lorm. 

OliTABDR 

address of the data to be transmitted from the aoplication. 

Specified as: register notation (2 through 12) or an SX address - 

Def atilt : none 

OUTLGE 

the length of the data pointed to by OBT.^DDR; maximum length is 
aOOO bytes. 

Specified as : the address of a fullword in register notation (2 
through 12) or an SX address. 

Default : none 

SIC 

a code identifying the le¥el of translation and editing to be done 
on the output data. 

Specifi ed as : 

SIC - data to be translated b'jt not edited 

1 - same as SIC 

2 - data to be Dassed untranslated and unedited 

Default: output data will be edited anel translated. 

the number assigned by Tl^II to be associated with the connected 
terminal that is to be scheduled for the requested operation. 

Specified as : the address of a half word in register notation (2 
through 12) or an BX address, or *aXL . If specified as *]ILL, or if 
the halfword value is set to X»FFFF*, all connected MTT users 
SYSIH/SYSOCTs will be scheduled for the requested operation. 

Def ault : user number 0, the task's owner. 

DECB 

identifies the ^6~byte DECB area to be used by lAMII. 

decb address 

specifies the address of the DECB 

S pecifi ed as: register notatioE (2 throuah 12) or an IX address. 

Default ; none 

name 

the name, label or symbol assigned to the DECB. 

Spe cified a s : one to eight characters, the first of which must be 
alphabetic. 
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J Default ; none 

1 

signifies that the DECB area is to be constructed as part of the 
macro expansion, immediately following the parameter list. 

Hote ; Before using a DECB area TAHII checks to determine that the area 
is available for use, that is, the area is not being used by some other 
request; if not in use, it clears all 48 bytes of the DECB. 



CPO 



the SYSOUT component for which this request is to be executed. 
Specifi ed as : 

- uses the value in the default SYSOUT. 

1 - uses the primary SISOOT. 

2 - uses the secondary SYSOUT. 

3 - uses the tertiary SYSOUT. 
L - uses the internal oueue. 

Default: uses the value in the default SYSOUT. 



BRK 



CC 



denotes the priority of the request. 

Specified as ; 

Y - top priority; this request will be scheduled ahead of any 
pending requests and will also interrupt any currently active 
request. 

N - not a priority request. 

Def ault : N 

specifies whether or not the outout data is preceded by a carriage 
control character. 

Specified as : Y (yes) or W (no) . 

Default: H 

In itializatio n: If this macro is to be executed in a privileged module, 
the most recently issued DCIASS macro in the assembly must have 
specified PRIVILEG2D. Also, the address of a save area must be placed 
in register 13 before this stacro is axecutt^d. 

Programming note ; prior to TA^'II, a GATWR followed by a GTHRC followed 
by another G&TWR in a nonconversational task vould have cause.3 a skip to 
a new page. This does not happen in TAfll . To skip a page in TIKII, 
issue TGATWR with CC=Y (the output data must start with the character 

»n»») . 

Return codes : the valid return codes, in register 15, are as follows: 

C ode leani ng 

X»00" request started successfully 

X»04» (for [ITT only) scheduling this output request has caused tho 

specified SYSOOT to reach it's buffer limit. Anv more 

requests should be delayed until an output complete return is 

received from a FINDO- 
X»03« attention received on this request; this return is possible 

only if OUT.^ODE=W. 
X»OC» the normal attention return code if the user presses attention 

key while the reouest is being scheduled for transmission. 
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X»18* user has passed an invalid parameter address or the length is 
zero^ or greater than 4000. If the DECS parameter is used, 
this return code is received if the DECB is still marked 
active for a previous request. 

X"24» see X»28» 

X»28« causes an ABEHD when the Driraary SISIU/SYSOUT was used; 

reflects a permanent I/O error for all other SISIN/SYSOUTs. 

Programming note : if a DECS operand is specified, the DECB may not be 
reused until either a CHCKT or a TCIEIR with TYPE=D has been issued 
against the DECB; otherwise, the request will be denied and a X"24" code 
will be returned. 



TGAYWS — Write to User's SYSOOT iS\ 

The TGATWS macro schedules a record to be transmitted to a specified 
user's primary SYSOUT. 

I 1 1 

IHame lOperation ^Operand 

I , , 

f[symbol]|TGATWS f [ oaTADDR=data address ][ ,OUTLGH=data lenqth ] 
I I |[ ,SIC= CSICI 1| 2} ][ ,OSII=user number] 

\ I |[ ,DECB=£decb address [ (name, Y) )][ ,BHK= fY [N} ] 

I I |[ ,CC={Yf!l}[ ,HF={irL» (E, address of L form)} 1 

I i_ I 

OOTABDB 

address of the data to be transmitted from the application. 

Specified as : register notation (2 through 12) or an FX address. 

Default : none 

OCTLGH 

the length of the data pointed to by OOTADDR; maximum length is 
4000 bytes. 

Sp ecified as: the address of a fullwori in register notation (2 

through 12) or an RX address. 

Default : none 

a code identifying the level of translation and editing to be done 
on the output data. 

Specified as : 

SIC - data to be translated but not edited 

1 - same as SIC 

2 - data to be oassei untranslated and unedited 

Def ault : output ^ata will be edited and translated. 

the number assigned by IAS II to be associated with the connected 
terminal that is to ba scheduled for the requested operation. 

Specixied as: the adiress of a half word in register notation (2 
through 12) or an RX address. 

Def ault : user number 0, the task's owner. 

DECB 

ideEtifies the 48-byte DECB area to be used by TA!*!!. 
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decb address 

specifies the address of the DECB 

..Spec ifi ed as: register notation (2 thrcioh 12) or an El address. 

Def ault : rone 

name 

the naaer label or symbol assigPied to the DECB. 

Sp ecified as: one to eight characters, the first of which sust be 
alphabetic. 

Def ault : none 

I 

signifies that the DFCb area is to^ be constructef' as part of the 
macro expansion^ iRimediately folloving the paraiLetar list. 

Note: Before using a DYC3 area TAKII chec!cs to determine that the area 
is available for use, that is, the area is not beina used by soae other 
request; if not in use, it clears all 48 bytes of the previous DECB. 

BRK 

denotes the priority of the request. 

Specified as : 

Y - top priority; this reauest will be scheduled ahead of any 
penrling requests and will also interrupt any currently active 
request - 

M - not a priority request. 

D efault : H 

specifies whether or not the output data is preceded by a carriage 
control character. 

S peciii ed as: Y (yes) or N (no) . 

Default : H 

Initializatio n: If this macro is to be executed in a privileged Eodule, 
the most recently issued DCLiSS macro in the assembly must have 
specified PRIVILEGED. Also, the address of a save area must be placed 
in register 13 before this macro is executed. 

Retu rn codes : the valid return codes, in register 15, are as follows: 

Code Keaninq 

X»00» request started successfully 

X»04» (for KTl only) scheduling this output request has caused the 

specified SYSOUT to reach it»s buffer lirait. Any iiore 

requests should be delayed until an output complete return is 

received from a FINDQ. 
X»08» attention received on this request; this return is possible 

only if OUTMODE=li. 
X'OC the normal attention return code if the user presses attention 

key while the request is being scheduled for transmission. 
X"18» user has passed an invalid parameter address or the length is 

zero, or greater than 4000. If the DECB parameter is used, 

this return code is received if the DECB is still marked 

active for a previous request. 
X»24» see X«28« 
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X«28» causes an ABEHD when the prisary SYSIM/SYSOOT »as used; 

reflects a permanent I/O error for all other SISIlVSTSOUTs . 



TGTWAP 



grit e and lea-l CS] 



The T&TK13 macro schelules a transmission on the soecified user^s 
SYSOUT ox the iata specified by the OUtADDF and OUTLGH operanvis; it also 
moves any lata froic the gueue or teriiinal into the area specifiel by the 

I^ADDB and I'^ILGH o'Deranc^s. 



1 1 ! "1 

IHaie 1 Operation [Operand | 


|[syiBboll|TGTWIR 


f 1 

f[ ,OOTADDF=aata address] [ ,O0TLGli=data length] I 




ir ,IMADDB=data address , TNLGH=aa ta length address] I 




|[ ,SIC=fSICf If 2|3 la j5)6 f7|6} [ ,0S2l=user nuokber] | 




f[,DECB=decb address] [ ,BRS= £Y | !«) [ , KODE= £«l f 1} ] | 




|[ r CCPI=sysiii number |CPO=sysout nasLer} ] | 




f[ ,CC=CYf!?] ] [ ,MF={I|I 1 (Headdress of L form)] ] | 



Note : if the £ and L form pair of this macro is user< , the SIC, BRK, CC 
anci MODE operands must be specified on the E form. 

ODTADDR 

address of the data to^ be transmitted from the application. 

Sp ecif ied as: register notation (2 through 12) or an PX address. 

Default: none 

OUTLGH 

the length of the data pointed to by ODTADDR; aaximom length is 
4000 bytes. 

Specified as; the address of a fullword in reaister notation (2 
through 12) or an RX address. 

Default: none 

INADBR 

address of the area to receive data to be sent to the application - 

Specified as : an address in register notation (2 through 12) or an 
RX address. 

Default: none 



INLGR 



SIC 



the length of the data pointed to by INADDE; maximum length is 4000 
bytes. 

Specified as: the address of a fullworl in register notation (2 
through 12) or an RX address. 

Default : none 

a code identifying the level of translation and editing to be done 
on the input/output data. 

Sp ecified a s : 

SIC - input data to be translated but not edited; output handled 
normally 

1 - same as SIC 

2 - output data to be translated but not edited; input handled 

normally 
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3 - both input and output to be translated but not edited 

4 - input data to be neither edited nor translated; out out 

handled normally 

5 - output data to be neither edited nor translated; input 

handled normally 

6 - neither input nor output data is to be edited or translated 

7 - input data to be neither edited nor translated; output data 

to be translated but not edited 

8 - output data to be neither edited nor translated; input data 

to be translated but not edited 

Default : both input and output data will be edited aKci translated. 

the number assigned by TEJfll to be associated with the connected 
terminal that is to be scheduled for the reouested operation. 

Spe cified as: the address of a half word in register notation (2 
through 12) or an HX address, or '^ALL . If specified as ^ALL, or if 
the half word value is set to X •????•, all connected FTT users 
SYSIN/SYSOUTs will be scheduled for the requested operation. 

Default: user number 0, the task's owner. 

DECB 

identifies the 43-byte DECB area to be used by TAHII. 

decb address 

specifies the address of the DECB 

Specified as : register notation (2 through 12) or an RX address. 

D efault : none 

name 

the name^ label or symbol assigned to the DECB. 

Specified a s: one to eight characters, the first of which must be 
alphabetic. 

Default: none 

Y 

signifies that the DECB area is to be constructed as part of the 
aacro expansion, immediately following the parameter lisx. 

H ote : Before using a DECB area TA'^II checks to determine that the area 
is available for use, that is, the area is not being used by some other 
request : if not in use, it clears all 4& bytes of the previous DECB. 

BEK 

denotes the priority of the request. 

Specified as : 

Y - top priority; this reouest will be scheduled ahead of any 
pending requests and will also interrupt any currently active 
request . 

N - not a priority request. 

Default : E 

MODE 

specifies how TAFII is to handle the input area. 

Spe cified a s : 
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E - input data is moved in to the user-provided area indicated by 
the IMIDDE and INLGH operands; on return, register contains the 
length of the data and register 1 points to the input area. 

L - input data is placed in a system allocated buffer; on return, 
register contains the length of the data, and register 1 points 
to the buffer- The buffer is released after the next reguest to 
schedule input is received. 

Defaul t: E 

the SYSIN component for which this reguest is to be executed. 

Specifie d as : 

- uses the value in the default SYSIN. 

1 - uses the primary SYSIN. 

2 - uses the secondary SYSIN. 

3 - uses the tertiary SYSIN » 
L - uses the internal queue - 

Defaul t: uses the value in the default SYSIN. 

the SYSODT component for which this request is to be executed. 
Specified a s : 

- uses the value in the default SYSOOT. 

1 - uses the primary SYSOUT. 

2 - uses the secondary SYSOOT. 

3 - uses the tertiary SYSOUT. 
L - uses the internal queue. 

Defaul t: uses the value in the default SYSOUT. 

specifies whether or not the output data is preceded by a carriage 
control character. 

Specified a s: Y ij bs) or N (no) - 

Defaul t; M 

I nitializatio n; If this macro is to be executed in a privileged module, 
the most recently issued DCLASS macro in the assembly must have 
specified PRIVILEGED. Also, the address of a save area must be placed 
in register 13 before this macro is executed. 

P rogramming note ; if the user or the application program is using any 
of the following implicit operands: 

INMODE=S SYSIN=L CPI=L 

the output transmission is not scheduled, but ignored, and the next 
input record from the input stack is returned to the caller. 

I R eturn code s; the valid return codes, in register 15 (byte 3) , are as 
follows: 

C ode M eanin g 

X*00» successful completion. Ilso, Register 15 may contain return 
codes in bytes and 2 which describe the input record- If 
byte of register 15 is X»80« the input is in cardboard 
format; if byte is X»00» the input is in keyboard format. 
Byte 2 may contain one of the following values: 
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X»00" - normal inptit 

X»01» - record ends with a continuation character 
X»02» - record truncated to fit user's input area; the 
rightmost characters have been lost 

X»04» device busy^ request scheduled 

X»08» attention received on this request 

X'OC" request not processed due to pending attention 

X*10" request purged by a TCLEAR request 

X«18* error in user's parameter list 

X"24» terminal has disconnected 

X»23» permanent I/O error on request 



T GfiSR -- i ri te wit h Synchronous Respons e CS> 

The TGTWSR macro transmits the data pointed to by the OUTADDP operand 
to the user's primary SYSOUT and returns to the application program the 
user's response from the user's primary SISIN. Ose of this macro in a 
nonconversational task causes termination of the task after the data has 
been transmitted to the user's primary SYSOUT if the user is the task 
owner. 



i "1 — T - " - ■■ - — - - - — 1 

IName (Operation | Operand I 


|[symbol IfTGTWSR |[ OUT ADDE=dat a address ][ ,,OUTLGH=data length] | 
1 1 f[ rIIIADDH=data ad dress rINLGH=data length address] | 
1 1 r[ ,SIC=[SICf1f2f3 |4|5|6f7|8}[ ,USM=user number ] \ 
1 1 |[ ,DECB = Cdecb address | {name, Y) }][ ,BRK= £Y [ N) | 
[ 1 |[ ,,MODE={M|L} ] 1 
1 1 |[ , CCPI=sysin num ber J CPO=sysout number}] | 
f 1 |[ ,CC = {Y| N} ][ ,MF= CI|L| CE,.address of L form)}] | 
1 1 . 1 1 



Note: if the E and L form pair of rhis macro is used, the SIC, BRK, CC 
and MODE operands must be specified on the E form. 

OUTADDR 

address of the data to be transmitted from the application. 

Specified a s; register notation (2 through 12) or an RX address. 

Defaul t; none 

OUTLGH 

the length of the data pointed to by OUTADDR; maximum length is 
4000 bytes. 

Specified a s; the address of a fullword in register notation (2 
through 12) or an RX address. 

Defaul t: none 

INIDDR 

address of the area to receive data to be sent to the application. 

S pecified a s: an address in register notation (2 through 12) or an 
RX address. 

Default: none 



INLGH 



the length of the data pointed to by INADDR; maximum length is ^+000 
bytes. 

Specified a s: the address of a fullword in register notation (2 
through 12) or an RX address. 
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Default: none 



SIC 

a code identifying the level of translation and editing to be done 
on the input/output data. 

Specifie d as : 

SIC - input data to be translated but not edited; output handled 
normally 

1 - same as SIC 

2 - output data to be translated but not edited; input handled 

normally 

3 - both input and output to be translated but not edited 

4 - input data to be neither edited nor translated; output 

handled normally 

5 - output data to be neither edited nor translated; input 

handled normally 

6 - neither input nor output data is to be edited or translated 

7 - input data to be neither edited nor translated; output data 

to be translated but not edited 
3 - output data to be neither edited nor translated; input data 
to be translated but not edited 

defaul t: both input and output data will be edited and translated. 

USN 

the number assigned by TAMII to be associated with the connected 
terminal that is to be scheduled for the requested operation. 

S pecifie d as: the address of a halfword in register notation (2 
through 12) or an RX address. 

Defaul t; user number , the task's owner. 

DECB 

identifies the 48-byte DECB area to be used by TAKII. 

decb address 

specifies the address of the DECB 

Specifie d as: register notation (2 through 12) or an EX address. 

Defaul t: none 

name 

the name, label or symbol assigned to the DECB. 

Specifie d as: one to eight characters, the first of which roust be 
alphabetic- 
Default: none 

Y 

signifies that the DECB area is to be constructed as part of the 
macro expansion, immediately following the parameter list. 

Note: Before using a DECB area TAKII checks to determine that the area 
is available for use, that is, the area is not being used by some other 
request; if not in use, it clears all 48 bytes of the previous DECB. 

BRK 

denotes the priority of the request. 

Specified a s : 
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Y - top priority; this request will be scheduled ahead of any 
pending requests and will also interrupt any currently active 

request. 

H ~ not a priority request. 

specifies how TIMll is to handle the input area. 

Specified a s : 

M - input data is moved in to the user-provided area indicated by 
the IMIDDE and INLGH operands; on return, register contains the 
length of the data and register 1 points to the input area. 

L - input data is placed in a system allocated buffer; on return, 
register contains the length of the data, and register 1 points 
to the buffer- The buffer is released after the next request to 
schedule input is received. 

Defaul t: M 

specifies whether or not the output data is preceded by a carriage 
control character - 

Specified a s: 1 (yes) or N (no). 

Default: M 

I nitialization : If this macro is to be executed in a privileged module, 
the most recently issued DCLASS macro in the assembly must have 
specified PEIVILEGED. Also, the address of a save area must be placed 
in register 13 before this macro is executed. 

f R eturn code s: the valid return codes, in register 15 (byte 3) , are as 

follows: 

C ode M eaning 

X»00« successful completion. Also, Register 15 may contain return 
codes in bytes and 2 which describe the input record. If 
byte of register 15 is X»80» the input is in cardboard 
format; if byte is X»00» the input is in keyboard format. 
Byte 2 may contain one of the following values: 

X*00» - normal input 

X'01" - record ends with a continuation character 
X*02» - record truncated to fit user's input area; the 
rightmost characters have been lost 

X'O^* device busy, request scheduled 

X*08* attention received on this request 

X«OC* request not processed due to pending attention 

X«10* request purged by a TCLEAR request 

X»18« error in user's parameter list 

X*2i4* terminal has disconnected 

X»23* permanent I/O error on request 

P rogramming note ; the TGfWSR macro can be used by the application 
program to synchronize an input record with an output record when the 
implicit operand I!IMODE=S. I'AHII will transmit the message (output 
data) to the primary SISOUT and then will return the user's response to 
the message as the input data. For nonconversational task owner's 
primary SYSIN/SYSOUT, input is always synchronized to output messages. 
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TRCBUF — Bead Terminal's Buffer C32 70 & 3066) tS) 



The TECBUF macro retrieves a line from the terminal's conversational 
buffer. 



-! 1 

\ Operation \ Operand 



f Name 



^ 

|[ OUTADDR =data address ][ ,OUTLGH=data 

|[ rmADDR=data address, INLGH=dat a length address] 

|[ ,DECB = {decb addressi (name,Y)] ][,USN=user number] 

f [ , {CPI=sysin number |CPO=sysout number)] 

|[ ,.HODE={tl|L} ][ ,.MF={I|L| (Ifaddress of L form)}] 



[symbol ]|TRCBOF 
I 
I 



OUTADDl 



address of an area that contains the frame number in EBCDIC of the 
line to be retrieved or a single blank character to denote a read 
of the next line. 
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Specified as ; register notation (2 through 12) or an EX address. 

Default ; none 

OOTLGH 

a fullword containing the length of the frame number. 

S pecified a s; register notation (2 through 12) or an BX address. 

D efault ; none 

IMADDR 

address of the area to receive data to be sent to the application. 

Specified as ; an address in register notation (2 through 12) or an 
RX address. 

Default ; none 

IHLGH 

the length of the data pointed to by INADDR; aaxiisua length is 4000 
bytes. 

Specified a s; the address of a fullword in register notation (2 
through 12) or an RX address. 

Default; none 

DECB 

identifies the 48-byte DECB area to be used by TaFII. 

decb addres*=; 

specifies the address of the DECB 

Specified as; register notation (2 through 12) or an RX address. 

Default ; none 

name 

the name, label or symbol assignee! to the DECB. 

Spe cified a s; one to eight characters, the first of which must be 
alphabetic. 

Default: none 

I 

signifies that the DECB area is to be constructed as part of the 
macro expansior, immediately following the paraaeter list. 

Note : Before using a DECB area Tiril checks to determine that the area 
is availai>ie for use, that is, the area is not being used by some other 
request; if not in use, it clears all 43 bytes of the previous DECB. 



DSK 



CPI 



the nuiLber assigned by TAMII to be associated with the connected 
terminal that is to be scheduled for the requested operation. 

Specified a s: the address of a half word in register notation (2 
through 12) or an ^1 address. 

Def aul t; user number 0, the task's owner. 

the sysiH component for which this reguest is to be executed. 
Specified as : 
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- uses the value in the default .^YSII. 

1 - uses the primary SYSIN. 

2 - uses the secondary SYSIM . 

3 - uses the tertiary 51 SIM. 

Default: none 



CPO 



the SYSOOT component for which this reauest is to be executed. 
Specified a s: 

- uses the value in the default SYSOOT. 

1 - uses the primary SYSOOT. 

2 - uses the secondary SYSOUT- 

3 - uses the tertiary SYSOUT . 

Default: none 

MODE 

specifies how TIKII is to handle the input area. 

Specified as : 

K - inout data is moved in to the user-provided area indicated by 
the IHADDB and INLGH operands; on return, register contains the 
lenath of the data an! reaister ^ points to the inout area. 

L - inout data is placed in a system allocated buffer; on return, 
register contains the length of the data, and register 1 points 
to the buffer- The buffer is released after the next reouest to 
schedule input is received. 

Default: M 

Init ializatio n: If this macro is to be executed in a privileged module, 
the roost recently issued DCLASS macro in the assembly must have 
specified PRIVILEGBD. Also, the address of a save area must be placed 
in register 13 before this macro is executed. 

Proqramgiinq note : either C^O or CPI should be given, but not both. If 
both are given, CPO is ignored and CPI is used. If CPI is not given, 
the request will be issued to the SYSOUT specified by CPO, or to the 
default SYSOUT if CPO is also not given. 

Return c odes : the valid return codes, in reaister 15, are as follows: 

C ode Mea ning 

X*00» successful request 

X"08« reached end of conversational buffer 

X»13* invalid parameter in reouest 

X«24" TFCBUF is not supported by specified SYSIN/SYSOUT 

Hote: the returned data line is in the following format: 

XXXXYYYZtext of line in EBCDIC 

where XXXX=the frame number, YYY=the line number, and Z=the attribute 
character for the line. 

TREAD — Device Dependent Direct Control Bead (3270s only) (S> 

The TREAD macro recuests an exact read type to be performed by TAMII; 
the data read is returned to the application program as received by 
TAHII. 
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name 



Operation (Operand 

4 



symbol JTREAD | INADDR=a ddress of input area 

[ rINLGH=address of length of input area 
I ,TYPE= PDBUF IRDMOD] 
I [ ,CPI=ad dress of component number] 
f[ ,DECB=fdecb address| (name^Y)} ] 
I [ ,OS!l=address of user number] 
r[,KF={Lf (Headdress of list)} ] 
I 



INADDR= 

the address of an area where the data, received by TAMII after the 
execution of the TREAD request, is to be moved. The data will be 
preceded by a 16-byte header created by TAKII. (See DSSCT CHISHDR 
for a description of the header.) 

Specified a s: register notation (2 through 12) or an RX address. 

Defaul t; none 

INLGH= 

the address of a fullword containing the length of the INADDR input 
area. 

Specified a s; register notation (2 through 12) or an RX address. 

Defaul t: none 

1IPE = 

a symbol defining the type of read channel program to be performed 
by TAMIL 

Specified as : 

RDBUF - perform a read full buffer operation (causes execution of 
an X»02» channel command word). 

RDMOD ~ perform a read modified fields operation upon receipt of an 
attention (causes execution of an X*06» channel command 
word) . 

Default: none 

CPI= 

the address of a half word containing the component number of the 
specified user's SYSIH for which the TREAD request is destined. 

Specified a s: register notation (2 through 12) or an RX address. 

Defaul t; uses the value in the default SYSIN. 

DECB = 

identifies the DECB to be marked upon completion of the TKRITE 
request. 

decb address 

specifies the address of the DECB 

Specified a s: register notation (2 through 12) or an RX address. 

Defaul t: none 

name 

the name, label or symbol assigned to the DECB. 
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S pecified a s: one to eight characters, the first of which must be 
alphabetic. 

Default: none 



signifies that the DECB area is to be constructed as part of the 
macro expansion, immediately following the parameter list. 

M ote : Before using a DECB^ area TAKII checks to determine that the area 
is a¥ailable for use, that is, the area is not being used by some other 
request; if not in use, it clears all 48 bytes of the previous DECB. 

USN = 

the address of a halfword containing the number of the user for 
which the TREAD request is destined. 

Specifie d as: register notation (2 through 12} or an RX address. 

Defaul t : user number 0, the task's owner. 

I nitializatio n : if thxs macro instruction is to be executed in a 
privileged module, the most recently issued DCLASS macro instruction in 
the assembly must have specified PRIVILEGED- Also, the address of a 
save area must be placed in register 13 before this macro instruction is 

executed . 

P rogramming n otes: this macro is only supported for use with the 3270 
display terminals. The use of this macro allows the application program 
to directly control the 3270 terminal. TAMII will pass to the user all 
data received from the 3270 terminal in response to the execution of the 
TREAD macro, except for a PA 1 response. T^MII maintains control of the 
PAI key for all cases. 

The data moved to the input area will be preceded by a 16-byte header 
described by the DSECT CHASHDR. This header area is added by the I/O 
section of TAMII and may or may not contain useful information depending 

on the previous write requests. 

The TREAD with TIPE=RDBUP is scheduled by TAKII to be executed as 
soon as any active and pending requests have been executed. A TREAD 
wirh TIPE=RDMOD is not executed until the receipt of an attention 
interrupt from the 3270 device. The TREAD with TIPE=RDMOD, upon 
reaching the top of the pending queue, causes any following requests to 
remain pending until the user has pressed one of the attention interrupt 
keys. The modified fields are read and the data is made available to 
the application program upon completion of the TREAD with TYPE=RDf?OD 
request . 

R eturn code s: upon return from a TREAD macro instruction registers 
and 1 will contain the length and address respectively, of the input 
data, and register 15 (byte 3) will contain a zero return code. If a 
DECB is specified or if register 15 is not zero, the contents of 
registers and 1 are not relative to the completion of the request. 

The following return codes are valid for a TREAD macro instruction: 

Cod e Meanin g 

X»00» successful completion. Also, Register 15 may contain 

returrn codes in bytes and 2 which describe the input 
record. If byte of register 15 is X'80» the input is in 
cardboard format; if byte is X'OO* the input is in 
keyboard format. Byte 2 may contain one of the following 
values: 
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X»08» 
X»OC» 

xno» 

XM8» 
X"20« 
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X»00» - normal input 

X»02« - record truncated to fit user's input area; the 
rightmost characters have been lost 

attention received while request was active 
attention received while request was pending 
request purged by a TCLEAR macro instruction 
user error in parameters specified 
request issued to a device other than a 3270 
permanent I/O error on request 
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I TWRIfE — Device Dependent Direct Control Write (3270s onlyl (S} 

The TWRITE macro instruction is used to reguest a specific write type 
to be performed by I^AMII . fhe application program is responsible for 
the data stream and display formatting. 



r 

Name 



Operation | Operand 



symbol JTWRITE fTYPE=symbol, O0TADDR=address of output data 
I ^OOTLGH-address of length of output data 
|[ ,INADDR=in area addr,INLGH=in area length addr ] 
|[ ,DECB=Cdecb address I (name, Y) } ] ],BRK=CT|li]] 
|[ ,USN=adaress of user number] 
|[ rCPO=address of output coaponent] 
([ ,MF={H (E,addr list)}] 
I ^ 



TYPE = 

identifies the type of write to be performed. 

Specified as : 

WRITE - write text to display (execution of an X»05» channel 
command word) . 

ER&SWRT - erase display and write text to display (execution of an 
X»05» channel command word). 

WETRD - write text to display and read response (execution of an 

X^OI' channel commaiii word followed by execution of an 

X'06» channel command word upon receipt of an attention 
interrupt) - 

EEAwE1*R - erase display, write text to display p and read response 
(execution of an X«05» channel command word followed by 
execution of an X"06» channel command word upon receipt 
of an attention interruDt) - 

Def ault : none 

OUTiDBR= 

the address of the formatted data stream to be written to the 
device. For Sills, TA!!II recruires that the text be preceded by a 
16-byte header. (See DSFCT CBASHRD for the header description.) 

SPecifiei as: register notation (2 through 12) or an FX address. 

Defaul t : none 

OBTLGB= 

the address of a fullword containiaa the length of the data stream 
to be written plus 16 bytes for the reguired header. 

Spec ifie d as: reaister notation (2 throuah 12) or an RX address. 

Def aul t : none 

I]IADDE= 

the address of an input area where the data read by THKII is to be 
moved . 

Specified as : register notation (2 throuah 12) or an RX address. 

Def ault : none 

Appendix M: lelecomiunications Access Method (TAMII) 34 3 



Page of GC2 8-2004-6 
Added 9 May 1979 
ByTNLGN20-3941 

INLGH= 

the address of a fullword containing the length of the INADDR input 
area. 

Spe cif ied as: register notation (2 through 12) or an FX a^'^.dress. 

Default : none 

DECB= 

identifies the DECB to te aiarked upon completion of the TI^RITE 
reguest . 

decb address 

specifies the address of the DECB 

Specifie d as: register notation {2 through 12) or an FX address. 

Default : none 

naae 

the name^ label or syiLbol assigned to the DECB. 

Specified, as: one to eight characters, the first of which must be 
alphabetic . 

Default. : none 

1 

signifies than the DECB area is to be constructed as part of the 
macro expansion, immediately following the parameter list. 

Note: Before using a DECB area TAFII checks to determine that the area 
is available for use, that is, the area is not being used by sone other 
request; if not in use, it clears all il3 bytes of the previous DECB. 

OSN = 

the address of a halfword containing the number of the user for 
which the TiRITE reguest is destined. 

S pecified as: register notation (2 through 12) or an FX address. 

Default: user number 0, the task's owner - 

CPO = 

the address of a halfword containing the component nuaber of the 
specified user's SYSODI' for which the TWIITE is destined. 

Specified as: reaister notation (2 throucrh 12) or an RX address - 

Default : uses the value in the default SYSOUT. 

B1K= 

specifies whether or cot this TWRITE reauest is of high priority. 

Specified a s : 

Y - the request is of high priority; it is gueued at the head of 
the pending I/O gueue and is to be started imicediataly . 

N - rhe reguest has no Briority. 

Default : N 

I nitialization : if this macro instruction is to be executed in a 
privileged nodule, the most recently issued DCLASS macro instruction in 
the assembly must have specified PRIVILEGED. also, the address of a 
save area must be placed in register 13 before this macro instruction is 
executed. 
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P rogramming note s: this macro is only supported for use with the 3270 
display terminals- The use of this Eacro allows the application program 
to directly control the 3270. When using TWBITE, the application is 
responsitle for all display formatting and keyboard resetting. It is 
the responsibility of the application program using a TWRIOjE to enable 
the keyboard if the user is to be able to enter input; TPEAD does not do 
a keyboard enable - 

When using TIPE=«BTRD or EEIiRTR, the operands IIIADDR and IMLGH must 
be specified- 

If the input options are coded, THKII returns all input read except 
for a PA 1 key interrupt (same as for TREAD). The PAI interrupt is 
restricted by TAF.II for use as the attention key. If the application 
program is to use the PAI key, it must follow normal TSS attention 
handling procedures using SIB, USATT, and CLATT . 

Upon return from a TWRITE without a DECB, if input data was to be 
read, registers and 1 will contain the length and address respectively 
of the input data. If input data is not expected, the contents of 
registers and 1 are not pertinent to the completion of the TWRITE. 

I R eturn code s; the following return codes (register 15, byte 3) are 
valid for a TWRITE macro instruction: 

Code E eaning 

f X»00« successful completion. Also, Register 15 may contain 

I return codes in byte and 2 which describe the input 

I record. If byte of register 15 is X»80» the input is in 

f cardboard format; if byte is X'OO* the input is in 

I keyboard format. Byte 2 may contain one of the following 

f values: 

I X«00* - normal input 

I X"02* - record truncated to fit user's input area; the 

I rightmost characters have been lost 

f X"0S» attention received while reguest was active 

X'0C» attention received while reguest was pending 

X'10* reguest purged by a TCLEAR macro instruction 

X»1&» user error in parameters specified 

X*20» request issued to a device other than a 3270 

X«28» permanent I/O error on request 

If the DECS operand is used, a zero return signifies that the reguest 
was scheduled for execution successfully. Any return code other than 
zero signifies that the condition occurred during the scheduling and the 
DECB is nor active. Therefore, the CHCKT for the DECB should be 
bypassed. If a zero is returned upon execution of TWRITE, the actual 
completion code will be returned upon return of the CHCKT issued against 
the DECB assigned to this re guest - 



TWRT LST — Perform Gat he r Write (S) 

The TWRTLST macro is a gather-write request. The application program 
passes a list of addresses and lengths and TAMII gathers all the data 
into one buffer and then schedules the buffer for transmission. Each 
entry in the list is assumed to be one printable line. 
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I 

I Name 



-i 1 

I Operation | Operand 




|[OUTADDR=data address ][ ,OUTLGH=data number] 

|[ ,SIC= {5ICM 12} ][ ,USN = iiser number] 

I [ ,DECB={decb address! (name, Y) }][ tCPO=sysout number] 

|[,BRK={ir|N} ][,CC = CY|!I} ] 

|[ ,EF={irLf (E, address of L form)}] 

Mote : if the E and L form pair of this macro is used the SIC, BEK, and 
CC operands must be specified on the E form. 

OOTIDDB 

pointer to a list of lengths and addresses on a fullword boundary, 
to be transmitted: for example, 

LGH1 ADDRl LGH2 ADD12 LGHN 

Specified a s: register notation (2 through 12) or an EX address. 

D efaul t: none 

OUTLGH 

pointer to a fullword containing the number of entries in the list 
(maximum of 64) . 

S pecified a s: the address of a fullword in register notation (2 
through 12) or an EX address. 



SIC 



USN 



DECB 



Default: 



a code identifying the level of translation and editing to be done 
on the data. 

Specified a s : 

SIC - data to be translated but not edited 

1 - same as SIC 

2 ~ data to be passed untranslated and unedited 

Defaul t; data will be translated and edited. 

the number assigned by flWII to be associated with the connected 
terminal that is to be scheduled for the requested operation. 

Specified a s; the address of a halfword in register notation (2 
through 12) or an EX address, or *ALL. If specified as *ILL, or if 
the halfword value is set to X»FPFF», all connected KTT users 
SYSIN/SYSOUTs will be scheduled for the requested operation. 

Def aul t: user number 0, the task^s owner- 
identifies the 48-byte DECB area to be used by TIKII. 



decb address 

specifies the address of the DECB 

S pecified a s: register notation (2 through 12) or an EX address. 

Default: none 



name 



the name, label or symbol assigned to the DECB, 



sue 
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Specified a s; one to eight characters, the first of which must be 
alphabetic. 

Defaul t; none 

Y 

signifies that the DECB area is to be constructed as part of the 
macro expansion, immediately following the parameter list. 

Note ; Before using a DECB area TAKII checks to determine that the area 
is available for use, that is, the area is not being used by some other 
request; if not in use, it clears all 48 bytes of the previous DECB. 

CPO 

the SISOUf component for which this request is to be executed. 
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BRK 



CC 



Specified as : 

- uses the value in the default SYSOOT. 

1 - uses the primary SYSOUT- 

2 - uses the secondary SYSOUT. 

3 - uses the tertiary SYSOOT- 

Default: uses the value in the default SYSOOT. 



denotes the priority of the request. 

Specified as : 

Y - top priority; this request will be scheduled ahead of any 
pending requests and will also interrupt any currently active 
request. 

N - not a priority recuest. 

Default: H 



specifies whether or not the output data is preceded by a carriage 
control character. 



Specified as : Y (yes) or H (no) . 

Default: N 

Init ialization : If this macro is to be executed in a privileged module, 
the most recently issued DCLASS macro in the assembly must have 
specified PRIVILEGED. Also, the address of a save area must be placed 
in register 13 before this macro is executed. 

Eeturn code s: the valid return codes, in register 15, are as follows: 

C ode Keani nq 

X»00« request started successfully 

X*0^« (for MTT only) scheduling this output request has caused the 

specified SYSOUT to reach it^s buffer limit. Any more 

requests should be delayed until an output complete return is 

received from a FIMDO- 
X»08* attention received on this reouest; this return is possible 

only if OT|TMODE=W. 
y'OC the normal attention return code if the user presses attention 

key while the reouest is being scheduled for transmission. 
X'lB" user has passed an invalid parameter address or the length is 

zero, or greater than 4000. If the DECB parameter is used, 

this return code is received if the DECB is still marked 

active for a i^revious reauest- 
I •24» see X 'ZS" 
X»23* causes an ABEilD when the primary SYSI'J/SYSOUT was used; 

reflects a permanent: I/O error for all other SYSIK/SYSOUTs. 



I TAP.II RACRO EXAWPLES 

i ExaEpies of the use of TAHII macro instructions for conaunicating 

I with the task owner ^s SYSIH and SYSODT are given below: these examples 
f illustrate the following: 

I • writing output to SlSOUf using the various output ootions 

f • reading inout from SYSH using the various input options; the 

I SOLICIT macro for requesting controlled input from SYSIll is also 

f illustrated 
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• the TCLEAR, TCMIRL an^ TDCKD macros for controllina the SYSIM 
and/or SYSODT 

• using DEC3s aBd the CHCKT macro for overlapped? I/O and procepsing 

• the correct method of haridling attentions by an amplication 
program than has replacel the system »s attention handler tfith its 
own 

Writing to S YSQOf 

TAMII supports a logical device concept. It is a simole device that 
understands an EBCDIC character strina which may contain some ootional 
control characters. When writing to this logical device, the 
application prograciHier issues a TAMII outi>iit oacro (i.e., TGIT^'H, TG?.TPS 
or TI^RTLST) pointing to a simple EBCDIC character string. TAMII will do 
all editing and translation reauired to make the output intelliqible to 
the actual SISOITT. For exar.ple, to write the message "GOOD SDINING* to 
any SYSOUT device the application prooranffier could code: 

IGJlTiiF 0CTADT)p=f!SG1 -OUTLGH=Lff SGI 



LMSGl DC k (L'^iSGI) 

f.SGl BC C'GOOD KOBHING* 

Ihis example results in the l^BCDIC ciiaracter stritg contained in area 
■MSGl'r whose length is conx-ained in the fullword 'L^SGl* to be written 
to the task owner's SYSOUT specified in the SYSODT operand or to the 
user's primary SYSOUT if the user's SYSOUT is defaulted. In the 
previous example the application programmer did not define (code) which 
SYSOUT would receive the message »GO0D FORMING'. The determination of 
the destination SYSOOT was up to the user, who could control tx, by 
setting the SYSOUT's value in the TAMII user's operand called 'SYSOUT* . 

If the application progranmer has to send the messaae to a particular 
SYSOUT, regardless of the user's SYSOUT value, there are two ways of 
doing so. One is by using the CPO operand on Til^^II macros to roote the 
message no the reguired SYSOUT- The programmer may do so as follows: 

TGAT^kR OUTAbDR=?lSGl,OUTIGH = LMSGl,CPO=CPOl 



LMSGl DC A(L»?!SG1) length or error messaae 

CP01 DC HM" number of SYSOUT component to receive 

rrSGl DC C'PARAKETES XXX IS INVALID* 

ine above example would cause the message to be written to the user's 
primary SYSOUT because of the value of the CPO operand. It could also 
direct: the message to either the user's secondary or tertiary SYSOUT by 
changing the value of the CPO operand to 2 or 3 respectively. 

Another way the application programmer can direct the message to the 
user's primary SYSOUT is to use the TGATWS macro; this macro always 
transmits to the user's primary SYSOUT regardless of the user's SYSOUT 
operand specification- As a result, there is no CPO operand in the 
TGATWS macro- The primary SYSOUT is assumed by TAMII when a TGATWS 
macro is executed by an application program- The previous example could 
have been coded using the TGATWS macro as follows: 

TGATWS OUTADDR=aSGl,OUTLGH=LMSGl 



LBSGl DC ACL'MSGI) 

NSG1 DC C'PABAMETER XXX IS Ili¥ILID' 



sua 
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The above exaiple ¥Oiil3 ¥rite the error message to the user's primary 
SYSO'OT following any otaer outout that had been issEed before the TGATiS 
Racro. For exaniDler if the application Drograpi had execotel six TGSTWSs 
and then execute I the TGATfeR or TGITIS in the previous two examples, the 
user woiild not see the error message until the first six TGATWS's output 
had been completed- If, however, the application programmer wanted a 
ttessage or output line to te given a hiah priority so as to be written 
to the user ahead of any Dending output, he can do so with the 3EK 
operand. When 5P.K=Y in any TI!-!!! Oijtput macro, lAKIl schedules the 
output recuest for immediate execution; for example: 

'lGh£'4h 0U1-IDDR=^SG1 ,OOI'LGH=LMSG 1 ,CP0=^CP01 ,BEK = I 



1KSG1 DC ACL'PSG!) 

CP01 DC H»1« 

aSGl DC C*A?P1ICATI0-!* SHOTDOWM SCHEDULED FOE 11:50* 

In tne above example a TGftTWl macro was used with the "break" option 
to send the user's primary SYSOOT a message about a pending scheduled 

shutdown. Instead of the TGATWH, tne application programmer could have 
used a I'GATWS to send the message- The BPK operand is valid for both 

macros . 

TIMII supports the FORTEH^ ISA carriage control characters for use 
with SISOOT output requests. TIHII assumes that the first character of 
the output data area is the ASA carriaae control when the CC=^Y operand 
of any TAKII macro is specified. TIP^II strips the first character from 
the output data and adds whatever control information is reauired to 
either perform or simulate the control function at the specified SYSOUI . 
The following exaciple illustrates an ISA control function -- skip to a 
new page — in an output write: 

TGATWR OUTADI)B = FSGl,aOTIGH = LPSGl,CC=Y 



LilSGl DC A(L«!ISG1) 

MSG1 DC CM THIS IS A NEW PAGE HEADER WRITE* 

For some TAMII supported units, a skip to new paqe function is 
siaiulated by doing a skip to new frame (3270s) or (for 2741s) a triple 
space follo'iied by the write of the output line. For device 
iraplemeetation notes on ASA characters refer to Figure 35. 

Tne previous examples all considered the writing of data from a 
single output area. TI^IT supports the writing of data from multiple 
data areas with a 'gather write ■ macro, TWRTLST- This macro allows the 
application programmer to supply a list of output areas with the length 
of the data in each area. TAMII validates the list and the data and 
then determines the most efficient way to transmit the data to the 
specified SYSOUT. Both the BRK and CC options apply to the TiRTLST 
macro- The BRK option signifies that the whole output is to be sent 
high priority and the CC option signifies that each element pointed to 
by the data list starts with an ASA control character. 

ihen using the TWRTLST macro, the application programmer first builds 
a list of 3-byte entries, starting on a fullword boundary, containing 
the length of the data and the address of the data to be transmitted to 
the user's SYSOUT. This list is pointed to by the OOTADDR operand; 
OUTLGH points to a fullword that contains the number of entries in the 
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fASI Carriage Control Simulation 
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I user message orompt overlay 


M 


treated as a single space by | 
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Figure 35. ASA Characters 

list. ine example below shows a TWRTLST that could be used to write a 
forsatted page of output using an ASA control character: 

!E'«RTLST 0UTADDR = LIST1,aUTLGE=lE!^TRY,CC=Y 



HEHTEY DC A ( (LIST3I-LIST 1) /3) number of entries in the list 

LISTI DC A (L»11SG1,MSG1) header line 

DC A CL»MSG2,ESG2) subheader line 

DC A (1 •KSG3,?^SG3) first text line 

DC A (L»I1SG4,MSG4) second text line 
LISTS EQU 

KSG1 DC C»l THIS IS 1H^ PAGE HEALER" skip to new page 

MSG2 DC C» THIS IS THE SUB HEADS?" write newline 
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KSG3 BC C»0 THIS HORHAL OUTPUT LINE" double space and write 
MSG4 DC C" THIS NEXT OUTPOT LIHE» text of page 

The use of the TIRTLST macro is more efficient for the system and the 
application programmer than attempting to write each line with an 
individual TGATtR. With TWFTLST, an application programmer can write up 
to 6 4 lines of output as long as the amount of output data, plus the 
number of lines times four, is less than or egual to 4000 bytes; i.e., 

X + ?IL*4 < 4000 

where X is the total amount of output data, and ML is the number of list 
entries . 

Along with BRK and CC there is a third operand that applies to the 
TGITWR, TGATWS, and TWRTIST macros — SIC. This option controls the 
editing ani translation that is to be performed by T2MII on the output 
data. ihen this operand is not specified, the output data is searched 
for control characters with defined functions, and those functions are 
performed or the control characters are deleted if the function is not 
supported on the receiving SYSOUT- After the search and edit, the 
output data is translated, using the user's translation table and 
retranslated if requested using one of two special tables used to fold 
lower case to upper case, or to fold upper case to lower case and lower 
case to upper case. Finally, the output data is translated to the line 
code expected by the receiving SYSOUT device. 

By using the SIC option the application programmer can turn off the 
above processes in favor of data transparency. By using one value of 
SIC for output, the application programmer can bypass all of TAMII"s 
editing and translation of output data to achieve data transparency. 

The following two examples show the use of two values of SIC to 
obtain special formatting results at the specified SYSOOT- The first, a 
no edit, line code translate only, for a 2741 is as follows: 

TGA'iWR 0UTADDR=?1SG1 ,0U-TLGH=LMSG1 ,SIC=1 



LKSG1 DC A CL»1"SG1 + L»FSG2) 

MSG1 DC C'THIS UNDBRLIII2S THE LIST WORD' 

KSG2 DC X"16161S16 1517171717* underline 5 do a new line 

Tae next example is a no edit, no line code translate for a graphic 
iTY3 3: 

TGATWR OUTADDR=aSGl ,00TIGH=LMSG1,SIC=2 



LFSGI DC A (L'KSGI) 

Reading froa SYSIN 

Since TAMII supports the logical device concept, the data received 
froa SYSIN by the application prograii is in the form of a variable 
length record, whose length is in register and whose address is in 
register 1- The data is an EBCDIC character stream with all control 
characters deleted. Each read retrieves one logical record from SYSIH. 
If the record is larger than the application orograa's input area, the 
record is trurcated to fit, by deleting the rightmost characters and a 
return coie indicatinq the truncation is set in reaistar 15 before 
control is returned to the application oroqram. The truncated data is 
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lost. A contiii nation return code is set in register 15 if the data ends 
with a coRtinuation character sequence which fulfills one of two 
continuation conventions. Ihe conventions used are determined by the 
origin of the SYSI!I data. If the data is entered at a keyboard, the 
last data caaracter must be the continuation character, blanks are not 
stripped. If the data is from a data set or a card reader , then either 
column 72 must be a non-blank or the last non-blank data character lust 
be a continuation character. In this case, blanks are striooed. 

Ihe lAKII iiacro instructions allow the application DrograFi to specify 
either move mode or locate ffi,ode by specifying ?!ODE=K or MOtL=L on the 
TAMII input reauest macros. Move mode causes TUMIT x.o move the 
retrieved loaical record to the input area specified by the macro 
instruction. locate mode causes TA?"II to provide a 256 byte input area 
where the retrieved record is placed and the address of this area is 
returned to the caller. On the next input recjuest, the allocated input 
area is released. 

An eiample of a normal SYSIH read follows: 

TGATRD I)IADDE=ABFA1,I:^LGH=IAREA1 



LAEEA1 DC ACL'AREAI) length of the input area 

AREAl DC IL256«0a» input area 

Upon return from the execution of the TGATED macro instruction 
register 15 will have a return code and register and 1 will have the 
length and address of the retrieve record- In this example the address 
in register 1 will be the address of AREAl and length in reaister is 
the actual length of the retrieved record. The contents of L»/^EA1 is 
not changed. The above exaikpla assumed move mode because K0DE=1 was not 
specified. The following example is the same as the one above except 
that MODE-L was specified: 

TGATRD rODE=L 



Since locate mode is specified the INaDDR and INLQH operands are not 
required . On return from the execution of the TGATED macro, register IS 
contains a return code and reaisters and 1 will contain the data's 
actual length and address respectively. The area pointed to by register 
1 will be released by TAMII upon execution of the next input macro 
instruction for this particular user's SYSI!i unit. 

As witti TGATKBs in the first two examples , both the user and the 
application programiLer have the capability to satisfy the input request 
from a specific SYSIN component. The user does it by setting his TAFII 
implicit operand SYSIN to name the particular SYSIN component that is to 
be used to satisfy the reguest. The application programmer does it by 
using a TAEII aacro with a CPT option and assigning to it the value of 
the SYSIN component to be used to satisfy the reguest. The foliowina 
example shows a locate mode request with an input component specified: 

TGATRD MODE=L ,CPI=C?I3 



CPI3 DC H»3» retrieve record from tertiary SYSIN unit 

So far in the examples for reading from SYSIH, TAMII would Eot have 
returned to the application proaram until the TGATKD reguest had been 
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sarisfied. If there was not a record available TAEIl would have taken 
whatever action was require-'^ to make the record available^ and then have 
waited until the record was available before returning. When overlapped 
I/O and execution is allowed by the user, TIKII provides the application 
prograiamer with a i&II operand for specifying whether TAHII is to wait 
until the record is available or to return. 

Wiien ^AIl is not specified or is specified as Y, TI^MII will not 
return ro the application program until a record is available to fulfill 
the request. It W]IIT=H , TA flII returns to the application immediately if 
there is no record available to fulfill the request. Ihe application 
proqrammer must test the return code in register 15 to determine if the 
request did retrieve a record- TAMII sets no indicator for the 
application program when a record is available. The application program 
must reissue the TGATRD to determine if a .record is available. The 
following shows the coding for a TGATFD with WAIT=N: 

Ti^ATED fODr = L/^IIT = ^ 

LI- 2,15 save miscellaneous return information 

N 15,=5? »OOOOOOFI » return code 0; record is available, 
* registers and 1 are valid 

BHZ TESTETC no record: test further 



TESTBTC DS OH 

CH B15,=I {UNA¥AI1) unavailable input return code 

bE NOr'SCOBD yes, go to no input label 

* error or attention encountered on TGATRD 

On an attention return code (X»03'), registers and 1 contain the 
data entered up to the attention. For all other return codes, except 
X'OD*, registers and 1 are unpredictable. 

Along with the TGATRD PACRO TAFII provides a complementary macro 
called SOLICIl'. This macro is used to initialize and start the 
controlled reading of records from a specific SYSIN. tiheii an 
amplication program executes a SOLICIT macro, TAMII initializes some 
tables and then dependina on the SOLICIT operands, starts retrieving 
records from the specific SISI*I- These records are placed in a gueue of 
tneir own, called the SOLICIT or data gueue. TAMII will continue to 
retrieve records from the STSI^ unit until one of the specified ending 
conditions is met. One of these records is made available to the 
application program each tine a TGATED without a TIPS operand r or with a 
TYPE=A (any) or D (data) is exacuted. Once all the records have been 
read by the application program and the SOLICIT ending condition has 
been reached, an EOD (end of data) code is returned in register 15. 

The SOLICIT macro allows the application program a flexible and 
controlled form of requesting input from the user. The SOLICIT 
mechanism can prompt the user with an incrementing number which also has 
a starting and ending number in addition to the increment value which 
can be specified. Also, the SOLICIT can just prompt with a static 
character prompt, or not prompt but just read each record as the record 
becomes available. The limiting or ending conditions can be specified 
by the application program as an ending number for an incrementing 
prompt, or as a number of lines to be read and/or specif yina a null line 
(a line without data) to end the SOLICIT reguest. The SOLICIT request 
will also be ended if a TGATPD with a TYPE=C is executed. The TSS 
command system always reads commands using a TGATRD with TYPE=C. This 
prevents possible SOLICIT input from being interpreted as a command. 
Anexample of a SOLICIT--TGATHD use is the TSS editor requesting input 
for an INSERT command. The insert module would execute the following 
SOLICIT macro followed by a series of TGATRDs to read the retrieved 
records: 
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SOLICIT PBHPT = START!»0,LEllG=MLEIfG,fIPE=D,IIICR = I?ICR10,E!iD=ESDN0 
this SOLICIT starts the prompting and reading of input 

TGATRD MODE=L,TYPE=D 

this TGATRD noM reads the input records 

CLM R15,B»0001»,, = IL1(BOD) end of SOLICIT return code? 



BHE SEADI 



no; go read next record, etc. 



STARTSO DC P»1000« 

FLBHG DC F»4« 

INCRHO DC PMOO" 

EHDHO DC P»2500« 



starting prompt number 
length of prompt 
increment 
ending number 



The SOLICIT 
(assuming the u 
first proapt wo 
with ^carriage" 
entered data in 
the current pro 
prompt with the 
the next prompt 
0001200b until 
SOLICIT request 
application pro 
the last input 



in the ab 

ser«s ISM 

uld be nu 

position 

response 

mpt value 

new numb 

would be 

2500 was 

would be 
gram on t 
record. 



ove example would cause TAMII t 
ODE=ii or B) the user for input 
mber 1000 in the line number fo 
ed after the blank . As soon as 

to the prompt, TARII would add 
, test the result against the e 
er if it was less than the endi 

0001100b, and the proiapt after 
reached. Once the 2500 value w 

ended and an EOD code returned 
he next TGATID after the TGATRD 



o start prompting 
records . The 
rmat of 0001000b 

the user had 

the increment to 
nding number, and 
nq number- So 

that would be 
as reached, the 

to the 

which had read 



Another SOLICIT example, one using an editor-like REDIT where there 
is no prompt and the ending condition is a null line could be coded as 
follows: 

SOLICIT TYPE=S,!IULL=Y,NIJM = LAF.GESU!! 






* 

# 



this SOLICIT will continue to read until ended by 
the user entering a null line 
TGATRD IUADDa=AEEAl,ISLGH=LAREA1,TIPr=D 
the TGATRD to do the actual transmission of data 
from TAMII to the application program 



LARGE^UM DC 
AREA1 DC 
LAREAl DC 



F«65000" 

XL256*00» 

F«256» 



large number to prevent 
endina on read count 



If the application program wanted to allow only a specific number of 
reads, the value for the !JOT paraaieter would be set to this number and 
TASII would end the SOLICIT when that nuiiber of reads had been reached. 

There are two other ways a SOLICIT itay be ended. One way is for the 
application program to execute a TCLBAF. TY^E=E. This causes the SOLICIT 
and any queued input to be purged . The other way is for the user to 
enter a data line which starts with a sinale command break character. 
This causes TA?III to force an early end to the SOLICIT input aueue and 
the record which started with the command break character is placed on 
the command queue to be read by the next TGATED with TYPE=C. 

TAMII provides the application programmer with two other nacro 
instructions to use when the user has to be prompted for input. One is 
TGTWAR — write with available response- It is used to write an output 
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record to a specific SYSOUT and to return the next available input 
record from a specific SYSIH. To use TGTWIE, the application programmer 
could code: 

TGTiAR 0UTADDB = I!SG1,0DTLGH=LESG1,INADDR=A1FA1, 

INLGH=LIRE11 



LHSGI DC A(L»MSG1) 

LAREAl DC A(L*IREA1) 

MSG1 DC C •READY FOR NEXT COIfKIND. E!«TEP • 

AREAl DC XL256»00» 

TGTWAR should be used for user predictable sequences and prompts. 
When the user is running with INttODE=S^ TAMII ignores the output portion 
of a TGJiTKAR and just returns the next gueued input line as the input 
record. By using TGTWAR for predictable prompts,, the user when using 
lNaODE=S can work ahead of the user's task because the user can predict 
with reasonable accuracy what the task is aoing to do. 

Since the TGTWAR is just a contraction of a TGATWF WITH A TGATRD, the 
several options that apply to the TGATWR and TGATRD macros also apply to 
the TGTWAR macro. TGTWAR does not support the TYPE and WAIT options of 
the TGATBD. As with the TGATWR and TGATRD macros the TGTWAR macro may 
be directed to a specific SYSOOT and SYSIH . The following example shows 
a TGTWAR which uses the BRK and CC options of TGATWR and the locate mode 
oDtion of a TGATRD: 

TGTIAR 0UTADDR=MSGl,0UrLGH=LMSG1yCC=Y,BRK=Y^M0DE=L, 
CP0=C?01,CPI=CPI1 



LH3G1 DC A(L"MSG1) 

FSGl DC C«0 DOUBIE SPACE A^D READ IHPOT • 

CP01 DC H»1« write and read the primary SYSOOT and SYSIN 

Upon completion of the TGTiAR macro in the last two examples^ 
registers and 1 will contain the length and address of the input 
record and register 15 will contain any associated return code. 

lor unexpected or unpredictable prompts that reouire a response, the 
application programmer should use the TSTWSR macro. TGTWSR is a write 
and real synchronous response operation directed to the primary SYSIH 
and SYSOOT. This macro is normally used by application proarais to 
request missing input parameters or when error conditions are 
encountered and the user ±s prompted as to what action is to be taken by 
the application program- In the example that follows the application 
program aas encountered some errors attempting to process certain data 
records anl prompts the user as to whether the records would te included 
in the report or deleted from the report- If the user is using 
IHXODE=S, the user may already have other command and input records 
enqueued waiting to be processed. If the application program executed a 
TGTWAR, TAFII would ignore the message and return the next available 
input line. So in the following exanple the application programmer has 
coded a TGTWSR lacro usincr ASA carriage control and locate mode input: 

TGTWSP OUTilDDF = i^>SGl,ODTLGB = LFSGl,CC=y rHODE=L 



LMSG1 LC A(L»MSG1) 

KSGl hC C'EMTER D 10 DELATE OR A TO ADD ERROR RECORDS TO REPORT* 
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Opon completion of the i-GTWSE fiacro in the above exami>le, registers 
and 1 will contain the length and address of the input recorl and 
register 1S will contain aDy associated return code- 
As with the output lEacro instructions x^GATWH, TGATiS^ and T'^RTLSl, 
TAKII supports an inout transparency mode. The SIC option is used to 
determine rhe amount of editing and translation to be done to the input 
record . 

The normal TAPII sequence of translation and editing for input is to 
first translate the inout record trom transEission line cole to EBCDIC. 
The input record is translated aqain to either fold, lower case ro uuper 
case or to reverse lower case to uuper case and upDer case to lo^er 
case. Next the input is scanned fox control characters. The function 
defined for the control character is performed and the control character 
is deleted from the inout record. And finally, the inout record is 
translated again, using the user's input translate table. 

3y specifying a value for SIC, the normal TAHII data aanipulation can 
be bypassed. The simple SIC value of 1 for ToATBD and a solicit' macro 
causes TAHII to bypass all editing and translations except the line code 
translate. A SIC value of 2 sets data transparency and the data will be 
passed, to the application in the form received from the user's SYSIN 
unit. The SIC operand for TGTWAR and TGTWSR is more complicated because 
both input and output can be treated separately. 

When using the SIC option with SOLICIT, both the SOLICIT and the 

TGATED macro instructions should specify the saae SIC values; if the SIC 
values are different, the results will be unpredictable. 

Biscellaneous Macros for Controlling SYSI N & SYSOUT 

Besides macros for moving data between the user and an application 
program, TAHII provides two macros which are used to directly control 
the 1/0 queues for the user's unit and to perform many device dependent 
miscellaneous control functions. The TCLEAR macro is used to purae 
specific reauests or types of reauests from both the pending and active 
request queues and the pending input queues. The TC^ITFL macro can be 
used to control the stopping and restartina of the pending request and 
to perform specific control functions at the user's specific 
sysih/sysout' unit. 

The TCLEAR macro purges requests from TAKII's pending I/O aueue- The 
pending I/O gueue has requests — TGATWR, TGATHD, etc. — which are 
scheduled but have not yet been started because the unit is busy with a 
previous reguest. The TCLEAR macro also stops and purges any active I/O 
if the active I/O meets the specified TCLEAR condition- Finally, the 
TCLEAR macro can be used to purge the pending input queues of input 
records. 

The application program identifies the purge condition by the TYPE 
operand on the TCLEAR macro. 

When TYPE=A (or ALL) , TAFII removes and releases all pending and. 
active I/O requests and releases any pending input records. For 
requests that have a DECS assigned, TAMII marks the DECS purged. Havinc 
been marked purged, the DECB is available for reuse without the need of 
a CHCKT aacro . If the application program executed: 

TCLEAR TYPE=A 

all queues, upon return froa TAMII, would be empty, any active DECBs 
wouia be marked purged, and the user's unit would be in an idle state. 
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The TCLEAF is alwafs pertormed synchronously to the aDplication program; 
i.e., iAFiIi does not ret^jni imtil the TCLEAP request has completed. 

TYPE=0' or OOTPUI causes TAFII to renove and release any pending 
output requests. li the reoaest is active, it is halted and released 
and anv DLZBs assigned to it are marked purged. Outout recruests are 
TGATWa, TGATWS, TC^ITBI, and TWHITE. (The TGTWAR, TGTIiSR and TwRITE 
(with response) macros are considered input requests by TAHII, since 
their main function is to read input.) All other requests are not 
afiected by this TY^E operand. In the followina example the TGATiR 
would be p-irged dj the following TCLEAP reauest^ but the TGTW!IP would be 
unaffected : 

TfilTWP OuTADDP = ?tSGl,aU'T'lGP = lESGl 



l-GTW.^R OUTADDF=£SG2,OUTLGF=LrSG2,KOD5=L 



TCLFAE lYPE-0 



Lf:SGl JjC ACL»ESG1) 

LMSG2 DC 5 {L»HSG2) 

MSGl DC C'ilESSAGE 1» 

ESC2 DC C'KESSAGF 2» 

2IPE=I or IKPUT is used to purge any pending input reguests and any 
input which has already been read by TIKII - Input reouests are SOLICIT, 
TG^TRD, TGTWAR^ TGATWSR, and TW3ITE {^ith input). Any other reouests 
are not affected by rhis TYPE ooerand. Ir an input request is active , 

it is halted and released. Any DECBs associated with it would be marked 
purged . 

TYPE=L or SOLICIT is used to purae a oendinq or active SOLICIT 
request and any input read by the SOLICIT- Ooon issuance of the TCLFAR 
macro the SOLICIT request is halted r if active, and released- Any input 
which has been read by the SOLICIT reouest is released. 

Caution : Khen INMODE=S any input in the input queue is considered 

SOLICIT input and is released. 

TYPE=D or DEC3 is used to purge a particular request. When a TCLEAB 
with TY?E=D is issued, all reouests are searched to locate the request 
associated with the specified DECS address. When the reouest is found, 
it is halted if active, and released, and the DBCB is marked purged. 

In the following exainple the TGATiR is associated with a DECB. After 
issuing the TGATWR, the application program decides to cancel the ,TGATWR 
request and only that request. This is accomplished by issuing the 
TCLEAR request with the DECS address and type code. This is the only 
way to cancel a particular request in TAWII. If the request does not 
have a DECB associated with it, it is not possible to do a specific 
cancel : 

TGATWR OUTADDR=^SG1,O0TLGH=LMSG1,DECB=DECBA 



TCLEAR TYPE=D,DECB=DECSA 
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CHCKT DECB=DECBI 
DECBA DC 12f»0» 
LMSG1 DC &(L«MSG1) 
KSG1 DC C'KESSAGE 1» 

Tke CHCKT in the above example will return a purged return code if the 
TGATll was pending or active. A return code of other than puraed will 
be returned if the TGATHR has already completed. 

Besides the TCLEAR macro, TAMII provides the application programmer 
with one other control macro instruction — TCHTHL. This macro is used 
to perform both device dependent and device independent control 
functions. The two independent functions supported are IHHIBIT and 
RESTAET. 

The issuance of a TCNTRL with TYPE=IliHIBIT causes the pending reguest 
queue to be placed in a hold state. At the completion of the currently 
active request, no pending reguest will be started until the hold state 
is reset by a TCKTRL with TYPE=PE START, or until the device is 
disconnected. 

A TCHTRL with TYPE=RESTAHT resets a hold state and restarts any 
pending requests. The hold state could have been set by a TCNTPL with 
TYPE=INHlBIi or by receipt of an attention from the device. Upon 
receiving an attention indication from a device, TAVII automatically 
puts the pending queue in a hold state and it is up to the attention 
handling routine to issue TCSTRL with TYPE=RESTAET to reset the hold 
state. The following example shows both a coded RESTART and an INHIBIT: 

STOP DS OH 

TC.^TRL TYPr=IIIHIBIT 



GO DS OH 

TCHTEL T Y?E=RES TART 

Asynchro nous Pr o ces s ing Usi ng CHC K T and DECB 

TAFII supports the use of DSCBs on all I/O reguest macros except the 
TGATRD. To test DECBs for completion, the TAMII CHCKT macro is used. 
•jZhis macro allows more flexible application programaing because of the 
programming objectives normally associated with interactive user 
support . 

The application programmer should be careful using DECBs with TAEII 
to avoid unnecessary overhead. Any output reouest which has a DECB 
associated reguires approxinately twice the system overhead to process, 
than one that does not have a DECB. This is because the DECB associated 
request after completion has to be posted back to the task by TAt'II so 
that the DECB can be marked complete and the completion status filled 
in; the reguest that does not have a DECB is released upon completion. 
The application Brogrammer should only use DECBs when knowledge of the 
completion of an operation is required. 

To use DECBs with TA!1I1 is simpla. The application programmer aay 
request TAttll to build a DECB and associate the DECB with a uacro at 
assembly time, or during execution can allocate and use as a DFCB 4 3 
bytes of storage. (Such storage must start on a fullword boundary.) 
The example below shows a TGiATWF with an assembly-time generated DECB. 
When this a^ethod is used the DECB is always generated at the end of the 
generated parameter list: 
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TGAI^WR 0UTADDE=MSGl^0tlTLGH=LMSG1,DSCB= (DECB1,I) 



The ■!■ as the second operand of the DECB operand signifies to the macro 
expansion that a DECB area called DECB1 is to be generated at the end of 
the macro expansion for the TGATWR macro. This same DECB area Bay be 
used by subseguent TAKII macros as long as the DECB is not currently in 
use. The following example shows this; the CHCKT in between the macros 
is require^; otherwise, when the second TGATIH was executed, the request 
would not be accepted because the DECB would still be marked in use with 
the first f GATWK : 

TGATIR 00TADDR=HSG1,001!LGH=LMSG1,DECB= (DECBl,!) 



ChCKT DECB=DECB1 



TGAIWB 0IITADDR = !flSG1,00TLGH=LMSG1,DECB=DECBl 



Once a DECB has been associated with a TAMII lacro either a CHCKT or a 
TCLEAR macro must have been executed for the DECB before it can be 
reused with a new lAMII macro. If this rule is not followed and a TAMII 
macro is executed with an in use DECB, TAMII will not accept the recruest 
and will return a user error return code. Also, if TAKII returns a 
non-zero return code on the execution of a macro with a DECB associated 
the CHCKT must not be executed. The DECB is not active, because the 
TAMII request was not accepted. 

Unlike the normal CHECK macro instruction with other a.ccBss methods, 
the application programmer can control whether TAKII waits for 
coBpIetion to be marked in the DECB or returns with a return code 
signifying that the request is still active. This it accomplished by 
the application proarammer using the WAIT oDtion on the CHCKT macro. If 
WAII=1, lAHII will test the D^CB and return to the caller with a return 
cole signifyina whether the request has completed or is still active. 
If WAIT=Y, TAP!II will not return until the request has been Dosted as 
coaplete, with or without errors. The following example shows two coded 
CHCKT macros, one with «AIT=N and the other with W AIT=Y : 

TGfiTWP 0UTADDB=«SG1,0UTLGH=LHSG1,DECB=DSCBB 



CHCKI DECB=DECSB,KAIT=.t test for completion 

CK R15, = 1ii»4» recruest completed? 

BE NOTDONE no, oo test for other work 

TGkx'rtR OOTADDR=:1SG1,OUTLGH=LMSG1,DECB=DECBB 



ChCriT DBCB=DECB3,WAIT=Y wait for completion 

Atte nti on Handling 

Attention handling with TAHII is relatively complex because of the 
input ana output bufferino capability. With output bufferina, TAMII, 
uoon receiving a user attention reauest, sets a software interlock to 
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prevent an? pending wrines from beina iT!itiate3. This software 
interlock prevents all pendinq requests from being started except a 

1-CLEAR, iFEES, or a TASII request which has the BPK=Y option set. 

TAKII contains an imi>licit operand called ATTMKODE that determines 
Mho does tiie reset and restart following an attention. If IIT'1'I"IM0DE = 0LB ,- 
task monitor (CZCJT) upon receipt of the attention, Durges the penlina 
queues and then resets the TSKII software interlock. If ITT'l?'oi)^=>fp:w, 
it is left to the attention handler to reset the interlock and to do anv 
other processing that may la necessary. 

For normal attentions , the sequence for the attention handlinq 
routine to follow would be a ICLBAR to purge all oending input and 
output, followed by a TC:iTRL to res^t the interlock. The following 
example shows this process followed by a promot for input: 

TCLEAR TypE=A purge all penlina input and output 
IC'STHL 1!YPE=BESTART reset sottware interlock 



TGT^^SR 0UTADDR=3*ISG1 ,OUTLGH=LrSG 1 ,Ib'TiDDR = IIHE A ,i:^LGH = LftF EA 



LMSG1 DC A(L»MSG1) 

LAREA DC ACL'AREA) 

MSG1 DC CENTER REQU:?ST« 

AREA DC XL256"00« 

By using the ATT^SA? macro it is possible to save a current set of 
pending input and output, and with ATTHt>st to restore it at a later 
tiite . For example, an application program, upon an attention, may issue 
a ATTMSA¥ to save all pending reauests, both input ami output. After 
the ATTSNSA?, the application program would issue a TCFTEL with 
TrPE=RESTART and then prompt the user for instructions. At a later 
time, on command from the user for instance, the aoplication program 
could issue an ATTNFST to restore the pending aueues and the user would 
be back to the state existing before the attention occurred. The 
following example shows the sequence of macro instructions needed to 
accomplish this result: 

ATTSSAV 

STH R0,B1,SAYL5V save attention level numbers 



TCNTRI TIPE=RESTART reset software interlock 



TGTiSR ... request action from user 



LH E2,R5,SI¥LEV get saved level numbers 

ATTHRST LE¥LIH=CE3) ,LEV0U1=CR2) restore attention 



SAVLE¥ DC 2F»0» save area for level 
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In the above example any of the TCLEAR macro instruction types could 
have been executed to purge requests that the application program ma^ 
not have wanted saved. For example, a TCLEAR with TYPE=0 could haife 
been executed to purge any pending output; then the AfTNSAV would only 
have saved the pending input records. Also, in the above example, an 
ATINDST could have been executed (instead of the ATTNRST) to delete any 
saved attention levels. 
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SAEC 192 

SAl 195 

SEEC 197 

SIEC 203 

SIB 205 

SPEC 208 

SSEC 210 

STEC 212 

USATT 230 
interruption inquiry 131 
interruption routine 
deletion of 93 
specification of 205 
writing 293 
interruption servicing logic 291 
interruptions 

attention key (TAMII) 344,342 

asynchronous (SAEC) 192 

external (SEEC) 197 

inhibition of 195 

input/output (SIEC) 20 3 

PA1 key (TAKII) 344,342 

program (SPEC) 208 

SVC (SSEC) 210 

timer (STEC) 212 
interval timer 215,227 
INTIKQ macro instruction 137 
I/O entry conditions 20 3 
I/O operation 

completion of 63 

reouest for 193 



143 
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iLr^ry (JOBLIB) , removal of 18 1 
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e 2 77 

operand) 277 
cessors 143-147 
ro instruction 141 
ch^ use of FIND 112 
ice facilities 29 8 

entions 260 
CALL, SAVE, and RETORN macro 

ions) 
loading 13 

6,25 



145 
84 

cro instruction 34 
neration of 284 
roup 34,35 

nstruction 142 
adcon group with 142 

module 142 
ARK 41 

e, deletion of 93 
dule 142,13 

and POT macro instructions) 

242 
rd length 80,269 
etters in operand 27 
o instruction 142 
o instruction 143 
perana) 80,269 






■e code 25 8 
fDCb operand) 82,269 
aii.i copy library 297 
instruction format 23 
iiiFtruction language 23 
i iiotructions 

,ditional assembly of 305,36 

■■'CUte torn 34 

;t .term 34 

, LvieM of services 1,2 

: V 13 e 3 6 



R-type 34 


S-type 34 


ABEND 37 


ADCON 39 


ADCOND 43 


lETD 44 


ARM 46 


ATTNDST 312 


ATTMRST 313 


ATTNSAV 314 


AiiAIT 47 


BPKDS 47 


BSP 49 


CALL 50 


CAT 54 


CDD 5b 


CHCKT 314 


CHDERMAC 59 


CHDPSECT 63 


CHDVAL 64 


CHECK 65 


CKCLS 66 


CLATT 66 


CLIC 66 


CLIP 6 6 


CLOSE 66 


CNTRL 70 


COMMAND 72 


CONSEG 73 


COPYDS 75 


CSTORE 75 


DCS 77 


DCBD 8 6 


DDEF 87 


DEL 90 


DELETE 92 


DELREC 93 


DELSEG 94 


DEQ 94 


DIAL 316 


DIR 95 


DISCSEG 96 


DQDBCB 99 


EBCDTIHE 103 


ENQ 105 


ERASE 106 


ESETL 108 


EXCSEG 108 


EXIT 108 


FEOV 109 


FIND 110 


FINDDS 112 


FINDJFCB 112 


FREEBUF 113 


FEEEMAIN 113 


FREEPOOL 115 


GATRD 116 


GATWR 119 


GDV 120 


GET 


QSAM 122 


?SAM 122 


GETBUP 12 4 


GETD? 125 


GETMAIN 126 


GETPOOL 129 


GETSEG 129 


GTWAR 130 
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GTWBC 132 


GTSSR 134 


HASH 136 


INTIIIQ 136 


lOHEQ 139 


LIBESRCH 141 


LOID 141 


LPCEDIT 142 


LPCI5iIT 143 


KABKIXRN 145 


MCI ST 14 6 


HOTE 152 


OBEI 154 


OPEN 155 


PAUSE 15B 


PIREC 159 


POIHT 159 


PE 161 


PRKP1 16 5 


PU 169 


PUT 


QSAK 172 


¥ISAM 172 


VSAM 172 


PUTS EG 173 


PUTX 


QSAM 173 


fSAK 173 


KAE 176 


READ 


BSIK 178 


¥ISAM 177 


EEDTIM 181 


PEL 18 2 


RELEX 184 


RELSE 184 


RELSEG 185 


EETOBH 186 


RSVSEG 167 


SAEC 192 


SAI 195 


SAVE 195 


SEEC 197 


SITDV 20 


SETL 


QSAR 200 


?1SAM 200 


VSAM 200 


SIEC 203 


SIR 205 


SOLICIT 317 


SPEC 208 


SSEC 210 


STEC 212 


STIEER 215 


STOW 219 


SYSIN 222 


TCLEAR 320 


TCNTRL 321 


TDCMD 324 


TFREE 325 


1-GATRD 327 


IGATWR 328 


TGATiS 331 


TGTWAR 3 33 


LGTWSR 336 


TRCBlii 338 


TREAD 340 



TRUNC 226 

TTIMER 227 

TWRITE 343 

TWRTLST 345 

USAGE 229 

OSATT 230 

VCCW 231 

VSEND 235 

WRITE 

BSAK 236 
VISAM 234 

Wf 239 

WTL 243 

WTO 2 43 

WTOA 2 45 

WTOR 246 

XTETK 247 
macro library 297 
magnetic tape positioning 68-71 
management of virtual storage 10 
MARKETRN macro instruction 145 
MCAST macro instruction 146 
member interlock 302 
message 
display of 165 

issued to SISOUT 148 

obtained from source list 222 

obtained from SYSIll 222 
mixed operands 25 
module 

called or calling 50 

deletion of 92 
move mode 

(see GET and PUT macro instructions) 
multi-level AETD interruption 

routines 295,44 
multiple SYSIVSYSOUT support 309 



name field 23 

for DCB 267 
names 

data set 30 

fully qualified 30 

generation 31 

member 31 

partially qualified 32 
NCP (DCB operand) 85,270 

non-privileged routine, assembly in 305,36 
normal program end 108 
notational symbols 26,27 
NOTE macro instruction 152 

use with POINT 153 



0~type macro instructions 36 
OBEY macro intructions 154 
off-line ptinting, writinq data set 

for 238 
OPEN macro instruction 155 
OPEH options 156,270 
OPEN parameter list 304 
operand 23,25 
operand forms 

keyword 25 

mixed 25 

operand string 2 6 

positional 25 
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operaad sublist 25 
o|ierator, coramunication with 15,242-2'*6 

kTO 2 42 

HfOA 244 

MfOI. 245 
OPT CD cr>CB operand) 81,270 
OPIIOM CI>DEF operand) 278 
OPTICKS (BCB operand) 270 
or, exclusive 26 

output JTiuffer, truncation of 226 
out. put aata set^ including record 
in 172,174 
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rand) 81,270 
ck 302 
f 93 

ew page 330 
ea 261 
St 260 
use of 
alif led 



27 

name 32 
organization directory 219 
instruction 158 

operand) 88,273 
instruction 159 

instruction 160 

MO-TE 160 

dback, provision of 152 

perand 25 

truction 16 1 

cter, control language 141 

ata set 161^238 

outine, assembly in 305 ,36 

instruction 165 

acter and switch table 146 

normal 108 
y conditions 208 
age macros 
nking and loading) 
gement 9 
g, command 143 
m for message 165 
F operand) 279 
ffibolic names for DCB fields 

macro instruction) 
truction 169 
ata set 169 
St ruction 



instruction 
nstruction 

173 
173 



173 



CSAI'l entry to SYNAD 2 52 

',)Sa?' macro instructions 7 
LBTIiL 72 
GET 122 
POT 172 
PUIX 174 
lELSE 184 
SETL 200 



TRUNC 226 

queue entry, contents of 291 
queued sequential access method 



E-type macro instruction 
RIE macro instruction 1 
read a block 178 
read a record 17 7 
read exclusive record 
read interlock 302 
READ macro instruction 

for BSAM 178 

for VISIM 177 
RECFM (DCB operand) 79, 
record concatenation cha 
record, deletion of 92 
record format 7 9,270 
record length 80,269 

incorrect 46 
recording technique, 7-t 
REDTIK macro instruction 
register contents 

restoration of 184 

saved 195 

VISAM SYNAD 256 
register notation 28 
register type macro inst 
register use, for linkag 
REL macro instruction 1 
relative generation name 
relative key position 8 
release a data set 108, 
release an access regues 
release an input buffer 
release read exclusive r 
release virtual storage 
RELEX macro instruction 
relocatable expression 
RELSE macro instruction 
RELSEG macro instruction 
Remote Job Entry 163 
remove a data set 9 

ERASE 105 

REL 181 
removing a job library 
replacing a record 173 
repositioning tape drive 
request entry, contents 
request I/O operation 1 
resource access 105 
resource statistics 229 
resource usage displayed 
restart request 311 
restore inhibit state 1 
retention period 278 
RET (DDEF operand) 279 
RETPD (DDEF operand) 27 
retrieval address for ?A 
retrieving DDEF commands 
return 

of buffer to pool 11 

to calling program 1 
RETURN macro instruction 
RJE (remote job entry) 
RK? (DCB operand) 81,27 
RSVSEG macro instruction 
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76 



177 
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racter 14 1 



rack tape 82 
181 
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ecord 
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113 




184 




28 




184 




185 





181 

s 70 
of 291 
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M, QSIM 270,271 
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3 -type macro ins t ruction 34 
SAEC macro instruction 192 
SII aacro instruction 195 
sa¥e area 

layout of 260 

reserving 26 1 
save inhibit ■ status 195 
save register contents 195 
SI¥E aacro iEstruction 196 
search chains 40 
SEEC aacro iEStruction 197 
sense bytes 255^238 
set enabled state 176 
set interval timer 215 
SETD? macro iiistmction 200 
SETL macro instruction, 200 
shared data set rcjlease 108 
sharing data sets 302 
SIC, use of on output 351 
use of on outpmr 3 56 
SlEC macro instruction 203 
siffil^le buffering bS 
SIR aacro instruction 205 
SOLICIT macro instruction 317 

use of 3 54 
source list^ message obtained from 222 
SPACE fDDEF operand) 276 
SPEC macro instruction 207 
specify asynchronous entry conditions 192 
specify external entry conditions 197 

specify interruption routine 205 
specify I/O entry conditions 203 
specify program entry conditions 20 7 
specify S¥C entry conditions 210 
specify timer entry conditions 212 
SSEC macro instruction 210 
start of sequential processing 200 
statistics, user 2 28 
S1*2C macro instruction 212 
STIHEE macro instruction 215 
storage-type macro instruction 34 
storage of control section 75 
STOW macro instruction 220 
sublist, operand 25 

supervisor call entry conditions 210 
symbol (operand form) 2 9 
symbolic library 2 9B 

use of CALL 299,.i00 
SYBhD (DCB operand) 81^271 
SYSAD routine 

actions in 2 SI 

DECS for 254 

entry durj^ng bSAK or QSiM 
operations 252 

entry during ¥isin operations 25 6 

register contents at entry to 25 2 
synchronous ¥AH page out 158 
SISEIECH routine iOO 
SISIM 

communicatioQ wxth 14 

getting record from 115 

message obtained from 222 
SYSIN attention interruption services 295 
SYSIM component ilO 
SYSIN macro instruction 222 
SYSINDEX routine 298^299 
SYSIS/SYSOUT macros 

fsee communicating with SYSIl/SYSOUT) 



multipl 
synchro 
SYSOUT 

communi 

compone 
writing 
system log 
system mac 
system ope 
with 242 
system ori 
AWAIT 
CHDEHMA 
CHDPSEC 
CHDVAL 
DEQ 9 4 
EHQ 10 
HASH 1 
LIBESRC 
LPCEDIT 
LPCINIT 
OSAGE 
¥SEND 
XTRTM 
system sco 
system tim 
SYSXBLD ro 



e support 310 
nizing input/output 

14 



338 



catxon witn 
nt 310 

record on 119,130 
, communication with 24 2 
ro instructions 16,17 
rator, communication 
-245 

ented macros 
47 

C 59 
T 63 

64 
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228 

235 

247 

pe 
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uti 



141 
42 

43 



mask 147 

conversion to EBCDIC 
ne 299,300 



103 



315,316 



70 



TAMII 308-36 1 

attention levels 

(see ATTNxxx macros) 

coding example 347-361 

control of 35 6-3 58 

data transparency 351 

editing and translation 351,356 

implicit operands 308,311 
overlap requests 315,353 
read requests 310 
read/write requests 
write requests 308 
tape control options 69 
tape drive repositioning 
task end, abnormal 37 
telecommunications access method 

(see TAMII) 
TCLEAR macro instruction 

use of 356 
TCNTRL macro instruction 

use of 358 
TDCMD macro instruction 
test interval timer 227 
TFREE macro instruction 
TGATED macro instruction 

use of 352 
TGATWR macro instruction 

use of 348 
TGATiS macro instruction 

use of 348 
TGTWAE macro instruction 

use of 355 
TGTWSR macro instruction 

use of 355 
time, conversion to EBCDIC 103 
timer 215,227 
timer entry conditions 212 
timer maintenance 16 

EBCDTIKE 103 
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321 


324 


325 


327 


328 


331 


333 


336 
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REDTIM 181 
STIREE 215 
TTIMEE 227 
trailer label ro 
transfer to conm 

(see command 
transient comman 
TRCBUF macro ins 
TR21D macro inst 
TBfCH (DCB opera 
TIOMC macro inst 
truncate an outp 
TSKIBEND data se 
TTIEER macro ins 
TillfE macro ins 
liRTLST macro in 
use of 350 



utine^ user's 66,24 9 

and mode 13 

system interface macros) 

d prefix character 141 

truction 338 

ruction 340 

nd) 82,266 

ruction 226 

ut buffer 226 

t 39 

truction 227 

truction 34 3 

struct ion 345 



uncataloging data sets 90 

UNIT CI>DEF operand) 275 

unloading a module 92 

upper-case letters, use of 27 

USAGE macro instruction 228 

USATT macro instruction 230 

user interruption facilities 290,29 1 

user program, source of data set 

attributes 264 
user resource statistics, format 

of 229,230 
user scope mask 148 
user statistics, display of 228 
user's trailer label routine 66,249 



¥CCi macro instruction 231 
¥ertical stroke 26 
virtual channel command word 231 
¥irtual index sequential access method 5 
virtual partitioned access method 6 
virtual sequential access method 5 
virtual storage allocation 126 
virtual storage data sets, sharing 302,30 3 
virtual storage management macros 10 
CKCLS 66 
CONSEG 73 
75 
93 

96 
108 
113 



CSTORE 

DELSEG 

DISCSEG 

EXCSEG 

FEEEHAIN 



tUfSEG 173 

BELSEG 185 

ISVSEG 187 
virtual storage, release of 113 
VISAM entry to SINAD 256 
VISAH macros 5 

DELEEC 93 

ESETL 108 

GET 122 

PUT 172 

READ 177 

RELEX 183 

SETL 200 

WRITE 234 
VOLUKl (DDEF operand) 276 
volume label 276 
volume serial number 277 
VPAW macros 6 

FIND 110 

STOW 219 
VSAM macros 5 

GET 122 

PUT 172 

PUTX 173 

SETL 192 
VSEND macro instruction 235 



WAIT, use of 
write a block 
write a data 
write interlo 
write to log 
write to oper 
with actio 
with reply 
write a recor 
on SISOUT 
with ca 
and rea 
write on tape 
WRITE macro i 
for BSAM 
for VISAM 
WT macro inst 
WTL macro ins 
WTO macro ins 
WTOA macro in 
WTOR macro in 



on input 353 

236 
set 238 
ck 302 

242 
ator 242 
n message 244 

245 
d 234 

114 
rriage control 132 
d record 134,130 

238 
nstruction 
236,8 



234,7 
ruction 
truction 
truction 
struction 



239 
243 
243 
24 5 



GETHAIN 126 

GETSEG 129 



struction 246 



XTRTM macro instruction 247 
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